Prepare 7.0: PHP 8.3-8.6, PHPUnit 12.5, Psalm as a tool

.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 ]
 

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<string, class-string<MailWrapperInterface>>`)
+- 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<MailWrapperInterface>`
+- **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

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`.

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/webrequest": "^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"
 }

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"
 >
     <projectFiles>
         <directory name="src" />

tools/psalm/composer.json

@@ -0,0 +1,5 @@
+{
+    "require": {
+        "vimeo/psalm": "^6.16"
+    }
+}