Version 6.0 - Major Update

[byjg]

Version 6.0 - Major Update

Overview

This major release brings significant improvements to the MailWrapper library, including dependency upgrades, enhanced type safety, modernized testing infrastructure, and comprehensive documentation. This version introduces several breaking changes that improve code quality and maintainability.

Major Changes

1. Dependency Upgrades

• byjg/convert: Upgraded from ^5.0 to ^6.0
• byjg/webrequest: Upgraded from ^5.0 to ^6.0
• PHPUnit: Upgraded from ^9.6 to ^10|^11
• Psalm: Updated to support ^5.9|^6.12
• PHP Support: Extended to include PHP 8.4 (>=8.1 <8.5)

2. Type Safety Enhancements

• Added strict return type declarations across all methods
• Added #[\Override] attributes to overridden methods for better IDE support
• Improved type hints in docblocks
• Enhanced nullable type declarations (e.g., ?ClientInterface instead of ClientInterface $client = null)

3. Method Signature Changes

MailerFactory Updates

• registerMailer(string $class) now has explicit void return type
• create() now accepts UriInterface|string instead of just string, providing more flexibility

Wrapper Method Signatures

• All wrapper classes now use proper return types
• Test helper methods have strict type declarations

4. Testing Infrastructure Modernization

Test Class Renaming

• BaseWrapperTest → BaseTestWrapper
• AmazonSesWrapperTest → AmazonSesTestWrapper
• FakeSenderWrapperTest → FakeSenderTestWrapper
• MailgunWrapperTest → MailgunTestWrapper
• PHPMailerWrapperTest → PHPMailerTestWrapper

PHPUnit Configuration

• Migrated to PHPUnit 10/11 XML schema
• Replaced deprecated convertErrorsToExceptions attributes with modern equivalents
• Added strict error handling (failOnWarning, failOnNotice, failOnDeprecation)
• Updated <filter><whitelist> to <source><include> (new PHPUnit format)

5. Documentation Overhaul

Complete restructuring of documentation into dedicated files:

• Getting Started - Installation and quick start guide
• Envelope - Email message configuration
• Connection Strings - URI patterns for different mail services
• Mailer Factory - Registration and creation of mailers
• Attachments - Working with attachments and embedded images
• Custom Wrappers - Implementing custom mail wrappers
• Exceptions - Error handling and exception types

README.md streamlined to focus on overview and links to detailed documentation.

6. CI/CD Improvements

• Updated GitHub Actions workflow for PHPUnit
• Added container options for better test isolation
• Upgraded checkout action to latest version

7. Code Quality

• Added Psalm and PHPUnit run configurations (.run/ directory)
• Fixed Psalm warnings and errors
• Improved code consistency
• Added composer scripts for test and psalm

Breaking Changes

Category	Change	Impact	Migration Path
Dependencies	byjg/convert upgraded to ^6.0	Code using v5 API may break	Update to byjg/convert 6.0 and review breaking changes
Dependencies	byjg/webrequest upgraded to ^6.0	Code using v5 API may break	Update to byjg/webrequest 6.0 and review breaking changes
Dependencies	PHPUnit upgraded to ^10|^11	Old PHPUnit 9 tests may not run	Update test suite to PHPUnit 10/11 format
Method Signature	MailerFactory::registerMailer() returns void	Code checking return value will break	Remove return value checks
Method Signature	MailerFactory::create() accepts UriInterface|string	Stronger typing	No changes needed (backward compatible)
Test Classes	Test base classes renamed	Projects extending test classes will break	Rename class references: - BaseWrapperTest → BaseTestWrapper - *WrapperTest → *TestWrapper
PHPUnit Config	Strict error handling enabled	Tests with warnings/notices will fail	Fix all warnings and notices in test suite
PHP Version	Minimum PHP 8.1 required	PHP < 8.1 not supported	Upgrade to PHP 8.1 or higher

Non-Breaking Enhancements

• Added #[\Override] attributes (improves IDE experience, no runtime impact)
• Enhanced type declarations in docblocks
• Improved code organization and structure
• Better null safety with proper nullable types

Migration Guide

For Library Users

1. Update dependencies:

   composer require byjg/mailwrapper:^6.0
   composer update

2. Update your code:

   • Remove any code that checks the return value of MailerFactory::registerMailer()
   • Ensure you're running PHP 8.1 or higher
   • Update byjg/convert and byjg/webrequest if you use them directly

For Contributors/Developers

1. Update test dependencies:

   composer update --dev

2. Rename test class extensions (if you extended test classes):

   • Update any references from BaseWrapperTest to BaseTestWrapper
   • Update any references from *WrapperTest to *TestWrapper

3. Fix PHPUnit compatibility:

   • Replace ->will($this->returnValue()) with ->willReturn()
   • Ensure all test methods have void return type
   • Fix any warnings/notices (now treated as failures)

4. Review Psalm/static analysis:

   • Run vendor/bin/psalm to check for type issues
   • Add proper type declarations where needed

Testing

All existing functionality has been tested with:

• PHPUnit 10 and 11
• Psalm static analysis
• PHP 8.1, 8.2, 8.3, and 8.4

Related PRs/Issues

• docs: Update documentation structure with comprehensive Docusaurus-co… #24 - Documentation structure update

---

Release Type: Major (6.0)
Backward Compatibility: Breaking changes present (see table above)
Recommended Action: Review breaking changes before upgrading