From 8d8343f6fe73d9de55622ffe0d81f21d2de41fa4 Mon Sep 17 00:00:00 2001 From: Joao Gilberto Magalhaes Date: Sat, 22 Aug 2026 19:28:13 -0400 Subject: [PATCH] Prepare 7.0: PHP 8.3-8.6, PHPUnit 12.5, Psalm as a tool Widen the PHP constraint to ">=8.3 <8.7"; the previous "<8.6" is exclusive and excluded PHP 8.6. Bump byjg/* dependencies to ^7.0. While 7.0 is unreleased these resolve to 7.0.x-dev from each component's 7.0 branch, via minimum-stability dev with prefer-stable. Pin PHPUnit to ^12.5 and move Psalm to tools/psalm/composer.json. Psalm enumerates supported PHP versions and no release lists 8.6, so as a require-dev it made "composer install" fail on the 8.6 build job before any test ran. "composer psalm" bootstraps the tool and runs it. CI: add PHP 8.6 to the matrix; the Psalm job runs on 8.5. Housekeeping: rename phpunit.xml.dist to phpunit.xml, carry the 6.x changelog onto this branch, and update CHANGELOG-7.0.md. --- .github/workflows/phpunit.yml | 10 +- CHANGELOG-6.0.md | 192 ++++++++++++++++++++++++++++++++ CHANGELOG-7.0.md | 44 ++++++++ composer.json | 12 +- phpunit.xml.dist => phpunit.xml | 0 psalm.xml | 2 +- tools/psalm/composer.json | 5 + 7 files changed, 257 insertions(+), 8 deletions(-) create mode 100644 CHANGELOG-6.0.md create mode 100644 CHANGELOG-7.0.md rename phpunit.xml.dist => phpunit.xml (100%) create mode 100644 tools/psalm/composer.json diff --git a/.github/workflows/phpunit.yml b/.github/workflows/phpunit.yml index fc5f29a..4dca2b0 100644 --- a/.github/workflows/phpunit.yml +++ b/.github/workflows/phpunit.yml @@ -18,6 +18,7 @@ jobs: strategy: matrix: php-version: + - "8.6" - "8.5" - "8.4" - "8.3" @@ -34,7 +35,7 @@ jobs: # for github/codeql-action/upload-sarif to upload SARIF results security-events: write container: - image: byjg/php:8.4-cli + image: byjg/php:8.5-cli options: --user root --privileged steps: @@ -44,10 +45,15 @@ jobs: - name: Composer run: composer install + - name: Composer (psalm) + + run: composer --working-dir=tools/psalm update --no-interaction + + - name: Psalm # Note: Ignoring error code 2, which just signals that some # flaws were found, not that Psalm itself failed to run. - run: ./vendor/bin/psalm + run: ./tools/psalm/vendor/bin/psalm --show-info=true --report=psalm-results.sarif || [ $? = 2 ] diff --git a/CHANGELOG-6.0.md b/CHANGELOG-6.0.md new file mode 100644 index 0000000..f5b89fd --- /dev/null +++ b/CHANGELOG-6.0.md @@ -0,0 +1,192 @@ +# Changelog - Version 6.0 + +## Overview + +Version 6.0 is a major release that updates the library for modern PHP standards, improves compatibility with the latest jwt-wrapper library, and adds comprehensive documentation. This release includes breaking changes that require code updates when upgrading from version 4.x. + +## New Features + +### PHP 8.1+ Support +- Added support for PHP 8.1, 8.2, 8.3, and 8.4 +- Upgraded to PHPUnit 10 and 11 for modern testing +- Added static analysis support with Psalm (versions 5.9 and 6.12) + +### Enhanced Documentation +- **Getting Started Guide** (`docs/getting-started.md`) - Installation, basic usage, and motivation +- **Configuration Guide** (`docs/configuration.md`) - Comprehensive configuration options and examples +- **RSA Keys Guide** (`docs/rsa-keys.md`) - Using RSA private/public keys for enhanced security +- **How It Works** (`docs/how-it-works.md`) - Architecture and internal implementation details +- **Security Guide** (`docs/security.md`) - Security considerations and best practices +- **API Reference** (`docs/api-reference.md`) - Complete API documentation for all classes and methods + +### Improved Code Quality +- Added PHP 8 attributes support (`#[Override]`) +- Implemented static data providers for PHPUnit 10+ compatibility +- Added comprehensive type hints throughout the codebase +- Suppressed expected warnings in session parsing with proper error handling + +### Enhanced CI/CD +- Updated GitHub Actions workflow to test against PHP 8.1, 8.2, 8.3, and 8.4 +- Added container options for better test isolation +- Improved build configuration for modern PHP versions + +### Composer Scripts +- Added `composer test` script to run PHPUnit tests +- Added `composer psalm` script to run static analysis + +## Bug Fixes + +- Fixed `gc()` return type from `bool` to `int|false` to match `SessionHandlerInterface` requirements +- Removed redundant null coalescing operators for `getCookiePath()` calls +- Fixed compatibility with jwt-wrapper 6.0 API changes +- Updated session data handling to use array format for JWT token creation + +## Breaking Changes + +| Component | Before (4.x) | After (6.0) | Description | +|-----------|--------------|-------------|-------------| +| **PHP Version** | `php: ">=8.0"` | `php: ">=8.1 <8.5"` | Minimum PHP version raised to 8.1, added upper bound for PHP 8.4 | +| **jwt-wrapper Version** | `byjg/jwt-wrapper: "4.9.*"` | `byjg/jwt-wrapper: "^6.0"` | Updated to jwt-wrapper 6.0 with breaking API changes | +| **PHPUnit Version** | `phpunit/phpunit: "5.7.*\|7.4.*\|^9.6"` | `phpunit/phpunit: "^10\|^11"` | Upgraded to PHPUnit 10/11 (breaking for custom tests) | +| **Namespace** | `use ByJG\Util\JwtWrapper;` | `use ByJG\JwtWrapper\JwtWrapper;` | JWT wrapper classes moved to dedicated namespace | +| **Class Names** | `JwtKeySecret` | `JwtHashHmacSecret` | Renamed for clarity and consistency | +| **Class Names** | `JwtRsaKey` | `JwtOpenSSLKey` | Renamed for clarity and consistency | +| **JwtWrapper API** | `createJwtData($data, $timeout)` | `createJwtData(['data' => $data], $timeout, 0, null)` | JWT data must be an array, additional parameters required | +| **gc() Return Type** | `bool` | `int\|false` | Updated to match PHP's SessionHandlerInterface specification | +| **Test Data Providers** | Instance methods with `@dataProvider` | Static methods with `#[DataProvider]` attribute | PHPUnit 10+ requires static data providers | + +## Upgrade Path from 5.x to 6.x + +### Step 1: Update System Requirements + +Ensure your environment meets the new requirements: +- PHP 8.1 or higher (up to PHP 8.4) +- Update your server or Docker containers if needed + +### Step 2: Update Composer Dependencies + +Update your `composer.json`: + +```bash +composer require "byjg/jwt-session:^6.0" +composer require --dev "phpunit/phpunit:^10" # If you have custom tests +``` + +### Step 3: Update Code - No Changes Required for Basic Usage + +**Good news!** If you're using the library with basic configuration, no code changes are required: + +```php +// This code works in both 4.x and 6.x +$sessionConfig = (new \ByJG\Session\SessionConfig('your.domain.com')) + ->withSecret('your super base64url encoded secret key'); + +$handler = new \ByJG\Session\JwtSession($sessionConfig); +session_set_save_handler($handler, true); +``` + +### Step 4: Update Advanced Usage (If Applicable) + +Only if you're directly using jwt-wrapper classes or extending the library: + +**Before (4.x):** +```php +use ByJG\Util\JwtKeySecret; +use ByJG\Util\JwtRsaKey; +use ByJG\Util\JwtWrapper; + +$key = new JwtKeySecret('secret'); +$rsaKey = new JwtRsaKey($private, $public); +``` + +**After (6.0):** +```php +use ByJG\JwtWrapper\JwtHashHmacSecret; +use ByJG\JwtWrapper\JwtOpenSSLKey; +use ByJG\JwtWrapper\JwtWrapper; + +$key = new JwtHashHmacSecret('secret'); +$rsaKey = new JwtOpenSSLKey($private, $public); +``` + +### Step 5: Update Tests (If You Have Custom Tests) + +If you have custom PHPUnit tests extending this library: + +**Before (PHPUnit 9):** +```php +/** + * @dataProvider myDataProvider + */ +public function testSomething($data) +{ + // test code +} + +public function myDataProvider() +{ + return [['test']]; +} +``` + +**After (PHPUnit 10/11):** +```php +#[DataProvider('myDataProvider')] +public function testSomething($data) +{ + // test code +} + +public static function myDataProvider() +{ + return [['test']]; +} +``` + +### Step 6: Run Tests + +Verify everything works: + +```bash +composer update +composer test # New script in 6.0 +composer psalm # New script in 6.0 - optional but recommended +``` + +### Step 7: Review New Documentation + +Review the new comprehensive documentation in the `docs/` folder to take advantage of new features and best practices. + +## Migration Checklist + +- [ ] Verify PHP version is 8.1 or higher +- [ ] Run `composer update` to get jwt-session 6.0 and jwt-wrapper 6.0 +- [ ] Test your application with the updated dependencies +- [ ] If using advanced features, update namespace imports +- [ ] If extending the library or using jwt-wrapper directly, update class names +- [ ] If you have custom tests, update to PHPUnit 10+ syntax +- [ ] Review new security documentation +- [ ] Consider running Psalm for static analysis: `composer psalm` + +## Notes + +- **No runtime behavior changes**: Sessions work the same way in 6.0 as in 4.x +- **Backward compatible for standard usage**: Basic session configuration requires no code changes +- **JWT tokens remain compatible**: Existing sessions will continue to work after upgrade +- **Enhanced security**: Consider reviewing the new security documentation for best practices + +## Dependencies + +Updated dependency tree: + +```mermaid +flowchart TD + byjg/jwt-session-6.0 --> byjg/jwt-wrapper-6.0 +``` + +## Support + +For issues, questions, or contributions, please visit: +- GitHub Issues: https://github.com/byjg/jwt-session/issues +- Documentation: See the `docs/` folder +- jwt-wrapper documentation: https://github.com/byjg/jwt-wrapper diff --git a/CHANGELOG-7.0.md b/CHANGELOG-7.0.md new file mode 100644 index 0000000..51070b6 --- /dev/null +++ b/CHANGELOG-7.0.md @@ -0,0 +1,44 @@ +# Changelog - Version 7.0 + +> **Status: in development.** This document tracks changes landing on the `7.0` branch. +> Nothing here is released yet, and the contents may still change. + +## Breaking Changes + +- None. + +## Requirements + +- PHP 8.3, 8.4, 8.5 and 8.6 are now supported: `"php": ">=8.3 <8.7"`. + The previous `<8.6` upper bound excluded PHP 8.6, since `<8.6` is exclusive. + +### ByJG dependencies + +- `byjg/jwt-wrapper` is now `^7.0`. + +While 7.0 is unreleased these resolve to `7.0.x-dev` from each component's +`7.0` branch, via `minimum-stability: dev` with `prefer-stable: true`. + +## Toolchain + +- PHPUnit updated to `^12.5`. +- Psalm moved out of `require-dev` into its own manifest, `tools/psalm/composer.json`. + + Psalm enumerates the PHP versions it supports and no published release lists + 8.6. As a dev dependency it made `composer install` fail on the 8.6 build job + before any test ran. It now installs separately, only for the Psalm job. + + `composer psalm` still works — it bootstraps the tool and runs it. + +- PHPUnit 13 is deliberately **not** used. It requires PHP `>=8.4.1`, breaking the + 8.3 floor, and needs `sebastian/diff ^9.0`, which stable Psalm 6.16.1 rejects — + a combination that silently resolves Psalm to an unreleased `6.x-dev` branch. + +## Continuous Integration + +- The build matrix now includes PHP 8.6. +- The Psalm job runs on PHP 8.5 and installs Psalm from `tools/psalm`. + +## Housekeeping + +- `phpunit.xml.dist` renamed to `phpunit.xml`. diff --git a/composer.json b/composer.json index ac59705..105eaca 100644 --- a/composer.json +++ b/composer.json @@ -9,16 +9,18 @@ "minimum-stability": "dev", "prefer-stable": true, "require": { - "php": ">=8.3 <8.6", - "byjg/jwt-wrapper": "^6.0" + "php": ">=8.3 <8.7", + "byjg/jwt-wrapper": "^7.0" }, "require-dev": { - "phpunit/phpunit": "^10.5|^11.5", - "vimeo/psalm": "^5.9|^6.13" + "phpunit/phpunit": "^12.5" }, "scripts": { "test": "vendor/bin/phpunit", - "psalm": "vendor/bin/psalm --threads=1" + "psalm": [ + "@composer --working-dir=tools/psalm update --no-interaction", + "tools/psalm/vendor/bin/psalm --threads=1" + ] }, "license": "MIT" } diff --git a/phpunit.xml.dist b/phpunit.xml similarity index 100% rename from phpunit.xml.dist rename to phpunit.xml diff --git a/psalm.xml b/psalm.xml index 241b742..5becc55 100644 --- a/psalm.xml +++ b/psalm.xml @@ -7,7 +7,7 @@ cacheDirectory="/tmp/psalm" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="https://getpsalm.org/schema/config" - xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"> + xsi:schemaLocation="https://getpsalm.org/schema/config tools/psalm/vendor/vimeo/psalm/config.xsd"> diff --git a/tools/psalm/composer.json b/tools/psalm/composer.json new file mode 100644 index 0000000..197dd5f --- /dev/null +++ b/tools/psalm/composer.json @@ -0,0 +1,5 @@ +{ + "require": { + "vimeo/psalm": "^6.16" + } +}