From c4be8dbdc6cb7c80b96d17b38cb2bf38784cbb31 Mon Sep 17 00:00:00 2001 From: Joao Gilberto Magalhaes Date: Mon, 10 Aug 2026 23:10:16 -0400 Subject: [PATCH 1/2] Update `byjg/webrequest` dependency to version ^7.0 in composer.json --- composer.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/composer.json b/composer.json index c5ed6b5..d76d03c 100644 --- a/composer.json +++ b/composer.json @@ -17,7 +17,7 @@ "php": ">=8.3 <8.6", "ext-curl": "*", "byjg/convert": "^6.0", - "byjg/webrequest": "^6.0", + "byjg/webrequest": "^7.0", "aws/aws-sdk-php": "~3.20", "phpmailer/phpmailer": ">=6.4.1" }, From c141e426b3c101dd740e1e5fa21589b2e892beac Mon Sep 17 00:00:00 2001 From: Joao Gilberto Magalhaes Date: Sun, 23 Aug 2026 21:12:57 -0400 Subject: [PATCH 2/2] 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 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.0 changelog onto this branch, and update CHANGELOG-7.0.md. --- .github/workflows/phpunit.yml | 10 ++- CHANGELOG-6.0.md | 154 ++++++++++++++++++++++++++++++++ CHANGELOG-7.0.md | 45 ++++++++++ composer.json | 12 +-- phpunit.xml.dist => phpunit.xml | 0 psalm.xml | 2 +- tools/psalm/composer.json | 5 ++ 7 files changed, 220 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..4b1b949 --- /dev/null +++ b/CHANGELOG-6.0.md @@ -0,0 +1,154 @@ +# Changelog for Version 6.0 + +Version 6.0 represents a major update to the MailWrapper library, focusing on improved type safety, modern PHP standards, and enhanced null-safety checks. This release includes several breaking changes that require attention when upgrading from version 5.x. + +## New Features + +### Enhanced Type Safety +- Added comprehensive type declarations throughout the codebase, including parameter types, return types, and property types +- Introduced PHPDoc annotations with generic types (e.g., `@var array>`) +- Added `#[\Override]` attributes to ensure proper method inheritance + +### Improved Null Safety +- Refactored mail wrappers with null-coalescing operators for safer null handling +- Enhanced null-safety checks in `PHPMailerWrapper`, `AmazonSesWrapper`, and `MailgunApiWrapper` +- Improved handling of optional URI components (username, password, host, port, scheme) + +### Documentation Improvements +- Comprehensive Docusaurus-compatible documentation structure +- New detailed documentation pages: + - Getting Started guide + - Envelope configuration guide + - Connection Strings reference + - Mailer Factory usage + - Attachments handling + - Custom Wrappers implementation + - Exception handling guide + +### Testing & CI Enhancements +- Updated PHPUnit configuration with improved structure and container options +- Enhanced GitHub Actions workflow configuration +- Added `composer test` and `composer psalm` scripts for easier development workflow + +## Breaking Changes + +| Aspect | Before (5.x) | After (6.0) | Description | +|--------|--------------|-------------|-------------| +| **PHP Version** | `>=8.1 <8.4` | `>=8.3 <8.6` | Minimum PHP version increased to 8.3, added support for PHP 8.4 and 8.5 | +| **byjg/convert** | `^5.0` | `^6.0` | Dependency upgraded to major version 6 | +| **byjg/webrequest** | `^5.0` | `^6.0` | Dependency upgraded to major version 6 | +| **PHPUnit** | `^9.6` | `^10.5\|^11.5` | Dev dependency upgraded to PHPUnit 10 or 11 | +| **Psalm** | `^5.9` | `^5.9\|^6.13` | Dev dependency supports Psalm 6 | +| **Test Files** | `*WrapperTest.php` | `*TestWrapper.php` | Test class files renamed from suffix pattern | +| **MailerFactory::create()** | `string $connection` | `UriInterface\|string $connection` | Now accepts PSR-7 UriInterface in addition to string | +| **MailerFactory::registerMailer()** | No return type | `void` return type | Explicit void return type added | +| **Type Strictness** | Relaxed null handling | Strict null-safety | All wrapper methods now use null-safe operators (`?->`) and null coalescing (`??`) | + +### Additional API Changes + +- **MailerFactory::registerMailer()**: Parameter now properly typed as `class-string` +- **PHPMailerWrapper**: URI property access now uses null-safe operators throughout +- **Envelope**: Minor adjustments for stricter type checking +- **Test namespace**: Test classes use proper PSR-4 autoloading with `Tests\` namespace + +## Path to Upgrade from 5.x to 6.0 + +### Step 1: Check PHP Version +Ensure your environment is running PHP 8.3 or higher: +```bash +php --version +``` + +If you're running PHP 8.1 or 8.2, you must upgrade to PHP 8.3+ before upgrading to MailWrapper 6.0. + +### Step 2: Update Dependencies +Update your `composer.json`: +```json +{ + "require": { + "byjg/mailwrapper": "^6.0" + } +} +``` + +Then run: +```bash +composer update byjg/mailwrapper +``` + +This will automatically update the required dependencies (`byjg/convert` and `byjg/webrequest` to version 6). + +### Step 3: Update Dev Dependencies (if applicable) +If you have PHPUnit or Psalm in your project: +```bash +composer update phpunit/phpunit vimeo/psalm --with-dependencies +``` + +### Step 4: Review Custom Implementations +If you have custom mail wrappers that implement `MailWrapperInterface`: + +1. Add proper type declarations to all methods +2. Add `#[\Override]` attribute to interface methods +3. Ensure null-safety in URI handling: + ```php + // Before + $host = $this->uri->getHost(); + + // After + $host = $this->uri?->getHost() ?? 'default-host'; + ``` + +### Step 5: Update MailerFactory Usage (Optional) +If you pass URI objects to `MailerFactory::create()`, ensure they implement `Psr\Http\Message\UriInterface`: +```php +use ByJG\Util\Uri; +use ByJG\Mail\MailerFactory; + +// Both styles now work: +$mailer1 = MailerFactory::create('smtp://user:pass@smtp.example.com'); +$mailer2 = MailerFactory::create(new Uri('smtp://user:pass@smtp.example.com')); +``` + +### Step 6: Run Tests +After upgrading, run your test suite to ensure compatibility: +```bash +vendor/bin/phpunit +``` + +If you use Psalm: +```bash +vendor/bin/psalm +``` + +### Step 7: Update Test Files (if extending MailWrapper tests) +If your project extends any MailWrapper test classes, note the renamed files: +- `BaseWrapperTest.php` → `BaseTestWrapper.php` +- `PHPMailerWrapperTest.php` → `PHPMailerTestWrapper.php` +- `AmazonSesWrapperTest.php` → `AmazonSesTestWrapper.php` +- `MailgunWrapperTest.php` → `MailgunTestWrapper.php` +- `FakeSenderWrapperTest.php` → `FakeSenderTestWrapper.php` + +## Bug Fixes + +- Fixed Psalm-related type issues for improved static analysis +- Improved null-safety checks preventing potential null pointer exceptions +- Enhanced SMTP authentication handling with proper null checks +- Fixed potential issues with missing URI components in wrapper configurations + +## Notes + +- All existing connection string formats remain compatible +- No changes to the public API for `Envelope` class usage +- Wrapper registration and usage patterns remain the same +- Documentation now available in comprehensive Docusaurus format + +## Migration Support + +If you encounter issues during migration, please: +1. Review the new documentation in the `docs/` directory +2. Check the updated examples in the README +3. File an issue on GitHub: https://github.com/byjg/php-mailwrapper/issues + +--- + +**Full Changelog**: https://github.com/byjg/php-mailwrapper/compare/5.0.2...6.0 diff --git a/CHANGELOG-7.0.md b/CHANGELOG-7.0.md new file mode 100644 index 0000000..df38e47 --- /dev/null +++ b/CHANGELOG-7.0.md @@ -0,0 +1,45 @@ +# 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/convert` is now `^7.0`. +- `byjg/webrequest` 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 d76d03c..e92a114 100644 --- a/composer.json +++ b/composer.json @@ -14,20 +14,22 @@ "prefer-stable": true, "minimum-stability": "dev", "require": { - "php": ">=8.3 <8.6", + "php": ">=8.3 <8.7", "ext-curl": "*", - "byjg/convert": "^6.0", + "byjg/convert": "^7.0", "byjg/webrequest": "^7.0", "aws/aws-sdk-php": "~3.20", "phpmailer/phpmailer": ">=6.4.1" }, "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 037de8b..c1976fd 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" + } +}