refactor: Add PHP 8+ type declarations for PHPStan Level 5

[ttsuru]

PHPStan Level 5 Compliance - Complete Type Safety

Achieved 100% PHPStan Level 5 compliance with comprehensive type declarations across the entire CakePHP 2.x codebase.

Achievement

PHPStan Level 5: 599 errors → 0 errors

All type safety issues have been resolved through systematic addition of type declarations, fixing type coercion issues, and resolving contravariance problems.

Comprehensive Type Declarations

Model Layer (265+ errors resolved)

• TreeBehavior: 265 errors - Complete method signatures
• Model, I18nModel: All methods with return types
• Behaviors: TranslateBehavior, ContainableBehavior, AclBehavior
• BehaviorCollection, ModelBehavior: Full type coverage
• AclNode, Permission: Complete type declarations

DataSource Layer

• DboSource: All methods with complete type signatures
• Database Drivers: Mysql, Postgres, Sqlite, Sqlserver
• DataSource, CakeSession, ConnectionManager: Full coverage
• Removed unsafe extract() usage in buildColumn()
• Fixed truncate() return type: PDOStatement|bool|null

Controller Layer

• Controller, Component: Base class type declarations
• Auth: All authenticators and authorizers (Base, Basic, Digest, Form, Actions, Controller, Crud)
• Components: Acl, Security, RequestHandler, Flash, Cookie, Session
• Acl Refactoring: Split PhpAcl into PhpAco and PhpAro classes
• Scaffold: Complete type declarations

Console Layer (46+ errors resolved)

• Shell, ShellDispatcher: Complete signatures
• Commands: AclShell (46 errors), SchemaShell (25 errors), ApiShell (13 errors), I18nShell, TestShell, ConsoleShell
• Tasks: ExtractTask (22 errors), CommandTask
• Helpers: TableShellHelper
• ConsoleOutput, ConsoleInput: Full type coverage

Core & Utilities

• Configure: Type declarations + bug fix
• App, CakeObject: Complete coverage
• I18n, L10n, Multibyte: All methods typed
• CakeEventManager, CakeEvent: Full coverage
• CakeText, Folder: Type declarations
• LegacyClassLoader: Changed autoload() to : void (spl_autoload_register requirement)

Error & Exception Layer

• All exception classes: Added $previous parameter support
• All exception classes: Type declarations for constructor parameters
• Property type declarations for message templates

Test Infrastructure

• CakeTestFixture: Updated signatures
• CakeBaseReporter, CakeHtmlReporter, CakeTextReporter: Type declarations
• Replaced SqlserverTestResultIterator with proper PDOStatement mocks
• All test mocks updated to return correct types

Global Functions (functions.php)

• debug(), h(), pluginSplit(), sortByKey(): Complete type declarations
• All global helper functions now fully typed

Code Quality Improvements

Multibyte Optimization

Simplified ASCII character conversion - removed unnecessary loops:

// Before (6 lines, inefficient)
$str = strtolower(chr($char));
$strlen = strlen($str);
for ($ii = 0; $ii < $strlen; $ii++) {
    $lower = ord(substr($str, $ii, 1));
}
$lowerCase[] = $lower;

// After (1 line, clear intent)
$lower = ord(strtolower(chr($char)));
$lowerCase[] = $lower;

Applied to both strtolower() and strtoupper() methods.

EmailConfig Interface

• New EmailConfigInterface for type-safe email configuration
• Updated UPGRADE.md with migration guide
• Ensures consistent email configuration across applications

Test Mock Improvements

• All database transaction mocks return proper boolean values
• Prevents type coercion issues with typed return values
• Improved test reliability

CI/CD Enhancements

• Added cs2pr integration for PHPStan results in Pull Requests
• PHPStan errors now display as inline PR annotations
• Improved developer experience for code review

Breaking Changes

EmailConfig Interface Requirement

All email configuration classes must now implement EmailConfigInterface:

// Before
class EmailConfig {
    public $default = [...];
}

// After
use Cake\Network\Email\EmailConfigInterface;

class EmailConfig implements EmailConfigInterface {
    public $default = [...];
}

See UPGRADE.md for detailed migration instructions.

Statistics

• Total Commits: 23
• Files Changed: 300+
• PHPStan Errors Resolved: 599
• Lines Changed: ~2000+ additions, ~1500+ deletions
• Test Coverage: All tests passing
• Code Style: PHPCS compliant

Key Learnings

Type Coercion Issues

Discovered that adding : bool return type to methods causes null to be converted to false:

public function commit(): bool {
    // Mock returns null by default
    // With : bool, null becomes false
    // Solution: Add ->willReturn(true) to mocks
}

Autoloader Return Types

PHP's spl_autoload_register() requires autoloaders to return void, not bool. The return value is ignored by PHP - it doesn't control whether subsequent autoloaders are called.

Array Type Checking

The pattern $keys === array_values($keys) correctly checks if array keys are sequential from 0, though it may appear redundant at first glance.

Related

• UPGRADE.md: Updated with EmailConfigInterface migration guide
• CHANGELOG.md: Documented all changes and bug fixes
• phpstan.neon: Level 5 configuration

---

This PR represents a major milestone in code quality and type safety for CakePHP 2.x, bringing it closer to modern PHP standards while maintaining backward compatibility.

[codecov]

Codecov Report

❌ Patch coverage is 87.30878% with 224 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/I18n/I18n.php	61.36%	17 Missing ⚠️
src/Console/Shell.php	65.21%	16 Missing ⚠️
src/Console/Command/ConsoleShell.php	0.00%	15 Missing ⚠️
src/Model/Datasource/DataSource.php	34.78%	15 Missing ⚠️
src/Console/Command/SchemaShell.php	53.33%	14 Missing ⚠️
src/Model/Datasource/DboSource.php	92.13%	14 Missing ⚠️
src/Controller/Scaffold.php	78.57%	12 Missing ⚠️
src/Model/ConnectionManager.php	59.09%	9 Missing ⚠️
src/Console/Helper/TableShellHelper.php	0.00%	8 Missing ⚠️
src/Controller/Controller.php	84.61%	8 Missing ⚠️
... and 41 more

📢 Thoughts on this report? Let us know!