From 31d30b6fa5a908cd9f7fd1f6ebd2af56b51bdaa6 Mon Sep 17 00:00:00 2001 From: Victor GREBOT Date: Mon, 15 Sep 2025 15:03:03 +0200 Subject: [PATCH] chore(docs): update UPDATE.md, CHANGELOG.md and add UPGRADE-4.0.md based on https://github.com/ccmbenchmark/ting/compare/master...4.X --- CHANGELOG | 23 ++++-- UPDATE.md | 37 ++++++++++ UPGRADE-4.0.md | 188 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 244 insertions(+), 4 deletions(-) create mode 100644 UPGRADE-4.0.md diff --git a/CHANGELOG b/CHANGELOG index e7f601c1..061fb94d 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,9 +1,24 @@ 4.0.0 (unreleased): - * BC add ping and setTimezone on DriverInterface - * BC deleted Metadata setter & getter - * BC deleted deprecated methods on Mysqli and Pgsql drivers - * BC deleted CCMBenchmark\Ting\Query\Generator::getByCriteriaWithOrderAndLimit, use CCMBenchmark\Ting\Query\Generator::getByCriteria + * BC PHP 8.0 dropped, minimum version is now PHP 8.1 + * BC All classes now fully typehinted with strict types and return types + * BC Pgsql Driver now uses native PHP 8.1+ PgSql\Connection and PgSql\Result classes instead of resources + * BC Serialization interfaces typehinted: SerializeInterface::serialize() and UnserializeInterface::unserialize() + * BC Added ping() and setTimezone() methods to DriverInterface + * BC Added ConnectionPoolInterface::setDatabaseOptions() method + * BC Deleted Metadata::getGetter() and Metadata::getSetter() methods + * BC Deleted deprecated getInsertId() methods on Mysqli and Pgsql drivers (use getInsertedId() instead) + * BC Deleted deprecated getInsertIdForSequence() on Pgsql driver (use getInsertedIdForSequence() instead) + * BC Deleted deprecated getInsertId() on QueryInterface and Query class (use getInsertedId() instead) + * BC Deleted Generator::getByCriteriaWithOrderAndLimit(), merged into Generator::getByCriteria() with $order and $limit parameters + * BC Deleted UnitOfWork::generateUid() and UnitOfWork::generateUUID() methods * New feature: HydratorValueObject allows hydrating simple objects without metadata using native fetch_object() methods + * New feature: ResultInterface now exposes fetchObject() method for value object hydration + * Improvement: UnitOfWork now uses WeakMap exclusively for internal entity storage (enhanced from PHP 8.0 implementation) + * Improvement: PHPStan analysis raised to level 7 with baseline significantly reduced (from ~2200 to <50 errors) + * Improvement: Type coverage tool added (tomasvotruba/type-coverage) with minimum thresholds: 97% return types, 85% param types, 83% property types + * Improvement: Rector configuration added for automated refactoring and code quality improvements (targeting PHP 8.0+) + * Improvement: PHPStan custom extension for properties (CCMBenchmark\Ting\PHPStan\PropertiesExtension) + 3.12.0 (2025-04-17): * add __debuginfo() in NotifyInterface to reduce context when dumping an entity diff --git a/UPDATE.md b/UPDATE.md index 4b231c2f..a1041ace 100644 --- a/UPDATE.md +++ b/UPDATE.md @@ -1,6 +1,43 @@ # Update file This file will track changes to public interfaces between 2 major versions. +## 4.0: +* PHP required version is now 8.1 +* All classes are now fully typehinted with strict types +* PHPStan level raised to 7 +* Rector configuration added for automated code quality improvements +* Serialization interfaces now have proper type hints: + * ```SerializeInterface::serialize()``` now returns ```mixed``` explicitly + * ```UnserializeInterface::unserialize()``` parameter is now typed ```mixed``` +* Pgsql Driver now uses native PHP 8.1+ PgSql classes: + * Internal ```$connection``` property type changed from ```resource``` to ```\PgSql\Connection``` + * Internal ```$result``` property type changed from ```resource``` to ```\PgSql\Result``` +* ConnectionPoolInterface: + * Added method ```setDatabaseOptions(array $options): void``` +* DriverInterface: + * Added method ```ping(): bool``` + * Added method ```setTimezone(string $timezone): static``` + * Removed deprecated method ```getInsertId()``` (use ```getInsertedId()``` instead) +* Mysqli Driver: + * Removed deprecated method ```getInsertId()``` (use ```getInsertedId()``` instead) +* Pgsql Driver: + * Removed deprecated method ```getInsertId()``` (use ```getInsertedId()``` instead) + * Removed deprecated method ```getInsertIdForSequence()``` (use ```getInsertedIdForSequence()``` instead) +* QueryInterface: + * Removed deprecated method ```getInsertId()``` (use ```getInsertedId()``` instead) +* Query class: + * Removed deprecated method ```getInsertId()``` (use ```getInsertedId()``` instead) +* Generator class: + * Removed method ```getByCriteriaWithOrderAndLimit()``` + * Method ```getByCriteria()``` now accepts ```$order``` and ```$limit``` parameters (merged functionality) + * All methods now have strict return type hints +* Metadata class: + * Removed method ```getGetter()``` + * Removed method ```getSetter()``` +* UnitOfWork: + * Removed deprecated method ```generateUid()``` + * Removed deprecated method ```generateUUID()``` + ## 3.0: * PHP required version is now 5.5 * Cache data are incompatibles with previous major version, you should clean your cache data diff --git a/UPGRADE-4.0.md b/UPGRADE-4.0.md new file mode 100644 index 00000000..a9e00808 --- /dev/null +++ b/UPGRADE-4.0.md @@ -0,0 +1,188 @@ +UPGRADE FROM 3.X to 4.0 +======================= + +PHP Version +----------- + +* PHP 8.0 support has been dropped. The minimum required version is now **PHP 8.1**. +* Update your `composer.json` to require `"php": ">=8.1"` + +Generator +--------- + +* The `Generator::getByCriteriaWithOrderAndLimit()` method has been removed. +* Use `Generator::getByCriteria()` instead, which now accepts optional `$order` and `$limit` parameters: + +```php +// Before (3.x): +$generator->getByCriteriaWithOrderAndLimit(['status' => 'active'], ['name' => 'ASC'], 10); + +// After (4.0): +$generator->getByCriteria(['status' => 'active'], ['name' => 'ASC'], 10); +``` + +Metadata +-------- + +* The `Metadata::getGetter()` method has been removed. +* The `Metadata::getSetter()` method has been removed. +* If you were using these methods, you should define custom getters/setters directly in your field configuration: + +```php +// In your Repository::initMetadata(): +$metadata->addField([ + 'fieldName' => 'myField', + 'columnName' => 'my_field', + 'type' => 'string', + 'getter' => 'getMyCustomField', // Custom getter method name + 'setter' => 'setMyCustomField', // Custom setter method name +]); +``` + +UnitOfWork +---------- + +* The `UnitOfWork::generateUid()` method has been removed. +* The `UnitOfWork::generateUUID()` method has been removed (was deprecated in 3.x). +* If you need unique identifiers, use PHP's built-in functions like `uniqid()` or `spl_object_hash()` directly. + +Query and Driver Methods +------------------------- + +### Removed getInsertId() Methods + +All deprecated `getInsertId()` methods have been removed. Use `getInsertedId()` instead: + +**QueryInterface and Query class:** +```php +// Before (3.x): +$query->getInsertId(); + +// After (4.0): +$query->getInsertedId(); +``` + +**DriverInterface, Mysqli\Driver, and Pgsql\Driver:** +```php +// Before (3.x): +$driver->getInsertId(); + +// After (4.0): +$driver->getInsertedId(); +``` + +**PostgreSQL sequences:** +```php +// Before (3.x): +$pgsqlDriver->getInsertIdForSequence('my_sequence'); + +// After (4.0): +$pgsqlDriver->getInsertedIdForSequence('my_sequence'); +``` + +Serialization Interfaces +------------------------ + +If you have custom serializers, update the type hints: + +**SerializeInterface:** +```php +// Before (3.x): +public function serialize($toSerialize, array $options = []): string + +// After (4.0): +public function serialize($toSerialize, array $options = []): mixed +``` + +**UnserializeInterface:** +```php +// Before (3.x): +public function unserialize($serialized, array $options = []) + +// After (4.0): +public function unserialize(mixed $serialized, array $options = []): mixed +``` + +Note: The `serialize()` method now returns `mixed` instead of `string` to support more flexible serialization formats. + +PostgreSQL Driver +----------------- + +* The PostgreSQL driver now uses native PHP 8.1+ `PgSql\Connection` and `PgSql\Result` classes instead of resources. +* This is an **internal change** and should not affect most user code. +* If you were using reflection or type checking on internal driver properties, update your code: + +```php +// Before (3.x): +// $connection was a resource + +// After (4.0): +// $connection is a \PgSql\Connection instance +``` + +DriverInterface - New Required Methods +--------------------------------------- + +If you have implemented custom drivers, you must implement these new methods: + +```php +interface DriverInterface +{ + // New methods in 4.0: + public function ping(): bool; + public function setTimezone(?string $timezone = null): void; +} +``` + +**Implementation example:** +```php +public function ping(): bool +{ + // Check if connection is alive + // Return true if connected, false otherwise +} + +public function setTimezone(?string $timezone = null): void +{ + // Set the database connection timezone + // e.g., for MySQL: SET time_zone = '+00:00' +} +``` + +ConnectionPoolInterface - New Method +------------------------------------- + +If you have implemented custom connection pools, you must implement: + +```php +interface ConnectionPoolInterface +{ + // New method in 4.0: + public function setDatabaseOptions(array $options): void; +} +``` + +Type Hints and Strict Types +---------------------------- + +* All methods have full type hints for parameters and return types. +* If you extend Ting classes or implement Ting interfaces, ensure your signatures match exactly. +* Pay special attention to: + - Return type declarations (`: void`, `: static`, `: mixed`, etc.) + - Parameter types (`string`, `array`, `?int`, etc.) + - Nullable types where applicable + +Example of updated method signatures: +```php +// Before (3.x): +public function setConfig($config) +{ + // ... +} + +// After (4.0): +public function setConfig(array $config): void +{ + // ... +} +```