chore(docs): update UPDATE.md and CHANGELOG.md

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

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

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
+{
+    // ...
+}
+```