From a490e0049dc21c59996d2d7154accf3145860f24 Mon Sep 17 00:00:00 2001 From: David Badura Date: Sat, 7 Nov 2026 12:03:46 +0100 Subject: [PATCH 1/4] Fix PHPStan errors after the PHPStan 2.2 update PHPStan 2.2 types variadic parameters as arrays that may have string keys, so the objects passed on to insertMany() and bulkWrite() no longer satisfied the list types and the baseline entries stopped matching. Normalizing the objects with array_values() also makes the $objects[0] access safe when a repository is called with named arguments. The mapping methods now declare that they throw UnknownPropertyPath, which PHPStan needs to accept a call whose result is unused in the tests. --- phpstan-baseline.neon | 24 ------------------------ src/Metadata/DocumentMetadata.php | 5 +++++ src/Repository/MongoDBRepository.php | 5 +++++ src/Repository/RangoRepository.php | 5 +++++ 4 files changed, 15 insertions(+), 24 deletions(-) diff --git a/phpstan-baseline.neon b/phpstan-baseline.neon index d71d325..2f9e3f0 100644 --- a/phpstan-baseline.neon +++ b/phpstan-baseline.neon @@ -72,18 +72,6 @@ parameters: count: 1 path: src/Repository/MongoDBRepository.php - - - message: '#^Parameter \#1 \$documents of method MongoDB\\Collection\:\:insertMany\(\) expects list\, array\\> given\.$#' - identifier: argument.type - count: 1 - path: src/Repository/MongoDBRepository.php - - - - message: '#^Parameter \#1 \$operations of method MongoDB\\Collection\:\:bulkWrite\(\) expects list\, non\-empty\-array\, array\{''\$set''\: array\\}\}\}\> given\.$#' - identifier: argument.type - count: 1 - path: src/Repository/MongoDBRepository.php - - message: '#^Parameter \#2 \$data of method Patchlevel\\ODM\\Hydrator\\DocumentHydrator\:\:hydrate\(\) expects array\, array\|object given\.$#' identifier: argument.type @@ -114,18 +102,6 @@ parameters: count: 1 path: src/Repository/RangoRepository.php - - - message: '#^Parameter \#1 \$documents of method Patchlevel\\Rango\\Collection\\>\:\:insertMany\(\) expects list\\>, array\\> given\.$#' - identifier: argument.type - count: 1 - path: src/Repository/RangoRepository.php - - - - message: '#^Parameter \#1 \$operations of method Patchlevel\\Rango\\Collection\\>\:\:bulkWrite\(\) expects list\\>\>\>, non\-empty\-array\, array\{''\$set''\: array\\}\}\}\> given\.$#' - identifier: argument.type - count: 1 - path: src/Repository/RangoRepository.php - - message: '#^Property Patchlevel\\ODM\\Repository\\RangoRepository\:\:\$collection with generic class Patchlevel\\Rango\\Collection does not specify its types\: TDocument$#' identifier: missingType.generics diff --git a/src/Metadata/DocumentMetadata.php b/src/Metadata/DocumentMetadata.php index bef9ff8..03be4c5 100644 --- a/src/Metadata/DocumentMetadata.php +++ b/src/Metadata/DocumentMetadata.php @@ -122,6 +122,7 @@ public function discriminatorFilter(): array return [$this->discriminatorField => ['$in' => $this->discriminatorValues]]; } + /** @throws UnknownPropertyPath */ public function propertyPathToFieldPath(string $propertyPath): string { return $this->propertyPathToFieldPathWithChildren($propertyPath, $this->fields)[0]; @@ -131,6 +132,8 @@ public function propertyPathToFieldPath(string $propertyPath): string * @param array $filter * * @return array + * + * @throws UnknownPropertyPath */ public function mapFilterToFieldPaths(array $filter): array { @@ -210,6 +213,8 @@ private function propertyPathToFieldPathWithChildren(string $propertyPath, array * @param array $orderBy * * @return array + * + * @throws UnknownPropertyPath */ public function mapSortingToFieldPaths(array $orderBy): array { diff --git a/src/Repository/MongoDBRepository.php b/src/Repository/MongoDBRepository.php index 4c9b03e..f6bc0e4 100644 --- a/src/Repository/MongoDBRepository.php +++ b/src/Repository/MongoDBRepository.php @@ -12,6 +12,7 @@ use Patchlevel\ODM\Metadata\DocumentMetadata; use function array_map; +use function array_values; use function count; use function in_array; use function iterator_to_array; @@ -40,6 +41,8 @@ public function __construct( /** @param list ...$objects */ public function insert(object ...$objects): void { + $objects = array_values($objects); + try { if (count($objects) === 1) { $object = $objects[0]; @@ -73,6 +76,8 @@ public function update(object ...$objects): void return; } + $objects = array_values($objects); + if (count($objects) === 1) { $update = $this->prepareUpdate($objects[0]); diff --git a/src/Repository/RangoRepository.php b/src/Repository/RangoRepository.php index 233ef7d..79018b8 100644 --- a/src/Repository/RangoRepository.php +++ b/src/Repository/RangoRepository.php @@ -12,6 +12,7 @@ use Patchlevel\Rango\Exception\QueryException; use function array_map; +use function array_values; use function count; use function in_array; use function str_ends_with; @@ -39,6 +40,8 @@ public function __construct( /** @param list ...$objects */ public function insert(object ...$objects): void { + $objects = array_values($objects); + try { if (count($objects) === 1) { $object = $objects[0]; @@ -78,6 +81,8 @@ public function update(object ...$objects): void return; } + $objects = array_values($objects); + if (count($objects) === 1) { $update = $this->prepareUpdate($objects[0]); From 9aa2592a1c537aaa6549663ca3997755280992ad Mon Sep 17 00:00:00 2001 From: David Badura Date: Sat, 7 Nov 2026 12:03:46 +0100 Subject: [PATCH 2/4] Run the MongoDB integration tests against 6.0, 7.0 and 9.0 MongoDB 8.x refuses to start on the current GitHub runners because their kernel is 6.19 or newer (SERVER-121912). 9.0 starts fine. --- .github/workflows/integration.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/integration.yml b/.github/workflows/integration.yml index b7fc8c0..1ea7fec 100644 --- a/.github/workflows/integration.yml +++ b/.github/workflows/integration.yml @@ -94,7 +94,7 @@ jobs: mongodb-version: - "6.0" - "7.0" - - "8.0" + - "9.0" env: MONGODB_URI: 'mongodb://localhost:27017' From 4e41672cb7c4c6a9442478cb30eb892555477c4e Mon Sep 17 00:00:00 2001 From: David Badura Date: Fri, 6 Nov 2026 16:56:55 +0100 Subject: [PATCH 3/4] Require patchlevel/hydrator 2 Hydrator 2 merged HydratorWithContext and NormalizerWithContext into the Hydrator and Normalizer interfaces, so the repositories now take a plain Hydrator and the normalizers in the docs and fixtures get the context argument. 2.1.1 is the first release that keeps array shape keys without a normalizer, which 2.1.0 dropped. DocumentHydrator no longer implements the Hydrator interface. In v2 that interface works on mixed data, while documents are always arrays and the class is only used inside the repositories. It is now internal and throws DocumentNotExtractable if the hydrator does not return an array. --- composer.json | 4 +- composer.lock | 447 ++++++------------ docs/field-mapping.md | 8 +- src/Hydrator/DocumentHydrator.php | 28 +- src/Hydrator/DocumentNotExtractable.php | 23 + src/Repository/MongoDBRepository.php | 4 +- src/Repository/MongoDBRepositoryManager.php | 4 +- src/Repository/RangoRepository.php | 4 +- src/Repository/RangoRepositoryManager.php | 4 +- .../Integration/Fixtures/SkillNormalizer.php | 8 +- tests/Unit/Fixtures/SkillNormalizer.php | 8 +- tests/Unit/Hydrator/DocumentHydratorTest.php | 45 +- 12 files changed, 246 insertions(+), 341 deletions(-) create mode 100644 src/Hydrator/DocumentNotExtractable.php diff --git a/composer.json b/composer.json index 73b1372..464386b 100644 --- a/composer.json +++ b/composer.json @@ -23,8 +23,8 @@ } ], "require": { - "php": "~8.3.0 || ~8.4.0 || ~8.5.0" , - "patchlevel/hydrator": "^1.23.0" + "php": "~8.3.0 || ~8.4.0 || ~8.5.0", + "patchlevel/hydrator": "^2.1.1" }, "require-dev": { "ext-mongodb": "^2.1", diff --git a/composer.lock b/composer.lock index d25dcfd..d5d9017 100644 --- a/composer.lock +++ b/composer.lock @@ -4,20 +4,20 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "62f5748cfa71c93540ae59976e6da108", + "content-hash": "b3d243383f03dfbbbf33a0992175ed32", "packages": [ { "name": "patchlevel/hydrator", - "version": "1.24.0", + "version": "2.1.1", "source": { "type": "git", "url": "https://github.com/patchlevel/hydrator.git", - "reference": "b33d9f92b25114156e9935c12c563195afdbeb13" + "reference": "092dae401161ae6beb54e02cded14eb2a5fd2dbc" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/patchlevel/hydrator/zipball/b33d9f92b25114156e9935c12c563195afdbeb13", - "reference": "b33d9f92b25114156e9935c12c563195afdbeb13", + "url": "https://api.github.com/repos/patchlevel/hydrator/zipball/092dae401161ae6beb54e02cded14eb2a5fd2dbc", + "reference": "092dae401161ae6beb54e02cded14eb2a5fd2dbc", "shasum": "" }, "require": { @@ -25,7 +25,6 @@ "php": "~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0", "psr/cache": "^2.0.0 || ^3.0.0", "psr/simple-cache": "^2.0.0 || ^3.0.0", - "symfony/event-dispatcher": "^5.4.29 || ^6.4.0 || ^7.0.0 || ^8.0.0", "symfony/type-info": "^7.3.0 || ^8.0.0" }, "require-dev": { @@ -36,7 +35,9 @@ "phpstan/phpstan": "^2.1.39", "phpstan/phpstan-phpunit": "^2.0.15", "phpunit/phpunit": "^11.5.53", - "symfony/var-dumper": "^5.4.29 || ^6.4.0 || ^7.0.0 || ^8.0.0" + "symfony/cache": "^6.4.0 || ^7.0.0 || ^8.0.0", + "symfony/var-dumper": "^5.4.29 || ^6.4.0 || ^7.0.0 || ^8.0.0", + "wnx/commonmark-markdown-renderer": "^1.6" }, "type": "library", "autoload": { @@ -58,17 +59,21 @@ "email": "david.badura@patchlevel.de" } ], - "description": "Hydrator", - "homepage": "https://github.com/patchlevel/hydrator", + "description": "A library for seamless hydration of objects to arrays - and back again, optimized for developer experience and performance", + "homepage": "https://patchlevel.dev/docs/hydrator/latest", "keywords": [ + "denormalizer", "hydrator", + "normalizer", + "object mapping", + "patchlevel", "serializer" ], "support": { "issues": "https://github.com/patchlevel/hydrator/issues", - "source": "https://github.com/patchlevel/hydrator/tree/1.24.0" + "source": "https://github.com/patchlevel/hydrator/tree/2.1.1" }, - "time": "2026-06-13T11:46:58+00:00" + "time": "2026-11-07T10:58:53+00:00" }, { "name": "psr/cache", @@ -172,56 +177,6 @@ }, "time": "2021-11-05T16:47:00+00:00" }, - { - "name": "psr/event-dispatcher", - "version": "1.0.0", - "source": { - "type": "git", - "url": "https://github.com/php-fig/event-dispatcher.git", - "reference": "dbefd12671e8a14ec7f180cab83036ed26714bb0" - }, - "dist": { - "type": "zip", - "url": "https://api.github.com/repos/php-fig/event-dispatcher/zipball/dbefd12671e8a14ec7f180cab83036ed26714bb0", - "reference": "dbefd12671e8a14ec7f180cab83036ed26714bb0", - "shasum": "" - }, - "require": { - "php": ">=7.2.0" - }, - "type": "library", - "extra": { - "branch-alias": { - "dev-master": "1.0.x-dev" - } - }, - "autoload": { - "psr-4": { - "Psr\\EventDispatcher\\": "src/" - } - }, - "notification-url": "https://packagist.org/downloads/", - "license": [ - "MIT" - ], - "authors": [ - { - "name": "PHP-FIG", - "homepage": "http://www.php-fig.org/" - } - ], - "description": "Standard interfaces for event handling.", - "keywords": [ - "events", - "psr", - "psr-14" - ], - "support": { - "issues": "https://github.com/php-fig/event-dispatcher/issues", - "source": "https://github.com/php-fig/event-dispatcher/tree/1.0.0" - }, - "time": "2019-01-08T18:20:26+00:00" - }, { "name": "psr/simple-cache", "version": "3.0.0", @@ -273,255 +228,18 @@ }, "time": "2021-10-29T13:26:27+00:00" }, - { - "name": "symfony/deprecation-contracts", - "version": "v3.7.1", - "source": { - "type": "git", - "url": "https://github.com/symfony/deprecation-contracts.git", - "reference": "f3202fa1b5097b0af062dc978b32ecf63404e31d" - }, - "dist": { - "type": "zip", - "url": "https://api.github.com/repos/symfony/deprecation-contracts/zipball/f3202fa1b5097b0af062dc978b32ecf63404e31d", - "reference": "f3202fa1b5097b0af062dc978b32ecf63404e31d", - "shasum": "" - }, - "require": { - "php": ">=8.1" - }, - "type": "library", - "extra": { - "thanks": { - "url": "https://github.com/symfony/contracts", - "name": "symfony/contracts" - }, - "branch-alias": { - "dev-main": "3.7-dev" - } - }, - "autoload": { - "files": [ - "function.php" - ] - }, - "notification-url": "https://packagist.org/downloads/", - "license": [ - "MIT" - ], - "authors": [ - { - "name": "Nicolas Grekas", - "email": "p@tchwork.com" - }, - { - "name": "Symfony Community", - "homepage": "https://symfony.com/contributors" - } - ], - "description": "A generic function and convention to trigger deprecation notices", - "homepage": "https://symfony.com", - "support": { - "source": "https://github.com/symfony/deprecation-contracts/tree/v3.7.1" - }, - "funding": [ - { - "url": "https://symfony.com/sponsor", - "type": "custom" - }, - { - "url": "https://github.com/fabpot", - "type": "github" - }, - { - "url": "https://github.com/nicolas-grekas", - "type": "github" - }, - { - "url": "https://tidelift.com/funding/github/packagist/symfony/symfony", - "type": "tidelift" - } - ], - "time": "2026-06-05T06:23:12+00:00" - }, - { - "name": "symfony/event-dispatcher", - "version": "v8.1.5", - "source": { - "type": "git", - "url": "https://github.com/symfony/event-dispatcher.git", - "reference": "7458da64220376b2e0dc2d8451bf43382c1ad297" - }, - "dist": { - "type": "zip", - "url": "https://api.github.com/repos/symfony/event-dispatcher/zipball/7458da64220376b2e0dc2d8451bf43382c1ad297", - "reference": "7458da64220376b2e0dc2d8451bf43382c1ad297", - "shasum": "" - }, - "require": { - "php": ">=8.4.1", - "symfony/deprecation-contracts": "^2.5|^3", - "symfony/event-dispatcher-contracts": "^2.5|^3" - }, - "conflict": { - "symfony/security-http": "<7.4", - "symfony/service-contracts": "<2.5" - }, - "provide": { - "psr/event-dispatcher-implementation": "1.0", - "symfony/event-dispatcher-implementation": "2.0|3.0" - }, - "require-dev": { - "psr/log": "^1|^2|^3", - "symfony/config": "^7.4|^8.0", - "symfony/dependency-injection": "^7.4|^8.0", - "symfony/error-handler": "^7.4|^8.0", - "symfony/expression-language": "^7.4|^8.0", - "symfony/framework-bundle": "^7.4|^8.0", - "symfony/http-foundation": "^7.4|^8.0", - "symfony/service-contracts": "^2.5|^3", - "symfony/stopwatch": "^7.4|^8.0" - }, - "type": "library", - "autoload": { - "psr-4": { - "Symfony\\Component\\EventDispatcher\\": "" - }, - "exclude-from-classmap": [ - "/Tests/" - ] - }, - "notification-url": "https://packagist.org/downloads/", - "license": [ - "MIT" - ], - "authors": [ - { - "name": "Fabien Potencier", - "email": "fabien@symfony.com" - }, - { - "name": "Symfony Community", - "homepage": "https://symfony.com/contributors" - } - ], - "description": "Provides tools that allow your application components to communicate with each other by dispatching events and listening to them", - "homepage": "https://symfony.com", - "support": { - "source": "https://github.com/symfony/event-dispatcher/tree/v8.1.5" - }, - "funding": [ - { - "url": "https://symfony.com/sponsor", - "type": "custom" - }, - { - "url": "https://github.com/fabpot", - "type": "github" - }, - { - "url": "https://github.com/nicolas-grekas", - "type": "github" - }, - { - "url": "https://tidelift.com/funding/github/packagist/symfony/symfony", - "type": "tidelift" - } - ], - "time": "2026-08-21T17:47:34+00:00" - }, - { - "name": "symfony/event-dispatcher-contracts", - "version": "v3.7.1", - "source": { - "type": "git", - "url": "https://github.com/symfony/event-dispatcher-contracts.git", - "reference": "c7de7a00ffb67842132da02ea92988a39ccd9f4e" - }, - "dist": { - "type": "zip", - "url": "https://api.github.com/repos/symfony/event-dispatcher-contracts/zipball/c7de7a00ffb67842132da02ea92988a39ccd9f4e", - "reference": "c7de7a00ffb67842132da02ea92988a39ccd9f4e", - "shasum": "" - }, - "require": { - "php": ">=8.1", - "psr/event-dispatcher": "^1" - }, - "type": "library", - "extra": { - "thanks": { - "url": "https://github.com/symfony/contracts", - "name": "symfony/contracts" - }, - "branch-alias": { - "dev-main": "3.7-dev" - } - }, - "autoload": { - "psr-4": { - "Symfony\\Contracts\\EventDispatcher\\": "" - } - }, - "notification-url": "https://packagist.org/downloads/", - "license": [ - "MIT" - ], - "authors": [ - { - "name": "Nicolas Grekas", - "email": "p@tchwork.com" - }, - { - "name": "Symfony Community", - "homepage": "https://symfony.com/contributors" - } - ], - "description": "Generic abstractions related to dispatching event", - "homepage": "https://symfony.com", - "keywords": [ - "abstractions", - "contracts", - "decoupling", - "interfaces", - "interoperability", - "standards" - ], - "support": { - "source": "https://github.com/symfony/event-dispatcher-contracts/tree/v3.7.1" - }, - "funding": [ - { - "url": "https://symfony.com/sponsor", - "type": "custom" - }, - { - "url": "https://github.com/fabpot", - "type": "github" - }, - { - "url": "https://github.com/nicolas-grekas", - "type": "github" - }, - { - "url": "https://tidelift.com/funding/github/packagist/symfony/symfony", - "type": "tidelift" - } - ], - "time": "2026-06-05T06:23:12+00:00" - }, { "name": "symfony/type-info", - "version": "v8.1.5", + "version": "v8.1.11", "source": { "type": "git", "url": "https://github.com/symfony/type-info.git", - "reference": "ceb48db5b38d6a48640c414be0c69d53980ae5c5" + "reference": "9fd1414061c4bbf953bcfc183b133cbfa0a73c73" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/type-info/zipball/ceb48db5b38d6a48640c414be0c69d53980ae5c5", - "reference": "ceb48db5b38d6a48640c414be0c69d53980ae5c5", + "url": "https://api.github.com/repos/symfony/type-info/zipball/9fd1414061c4bbf953bcfc183b133cbfa0a73c73", + "reference": "9fd1414061c4bbf953bcfc183b133cbfa0a73c73", "shasum": "" }, "require": { @@ -570,7 +288,7 @@ "type" ], "support": { - "source": "https://github.com/symfony/type-info/tree/v8.1.5" + "source": "https://github.com/symfony/type-info/tree/v8.1.11" }, "funding": [ { @@ -590,7 +308,7 @@ "type": "tidelift" } ], - "time": "2026-08-21T17:47:34+00:00" + "time": "2026-11-02T10:58:30+00:00" } ], "packages-dev": [ @@ -3442,6 +3160,56 @@ }, "time": "2022-11-25T14:36:26+00:00" }, + { + "name": "psr/event-dispatcher", + "version": "1.0.0", + "source": { + "type": "git", + "url": "https://github.com/php-fig/event-dispatcher.git", + "reference": "dbefd12671e8a14ec7f180cab83036ed26714bb0" + }, + "dist": { + "type": "zip", + "url": "https://api.github.com/repos/php-fig/event-dispatcher/zipball/dbefd12671e8a14ec7f180cab83036ed26714bb0", + "reference": "dbefd12671e8a14ec7f180cab83036ed26714bb0", + "shasum": "" + }, + "require": { + "php": ">=7.2.0" + }, + "type": "library", + "extra": { + "branch-alias": { + "dev-master": "1.0.x-dev" + } + }, + "autoload": { + "psr-4": { + "Psr\\EventDispatcher\\": "src/" + } + }, + "notification-url": "https://packagist.org/downloads/", + "license": [ + "MIT" + ], + "authors": [ + { + "name": "PHP-FIG", + "homepage": "http://www.php-fig.org/" + } + ], + "description": "Standard interfaces for event handling.", + "keywords": [ + "events", + "psr", + "psr-14" + ], + "support": { + "issues": "https://github.com/php-fig/event-dispatcher/issues", + "source": "https://github.com/php-fig/event-dispatcher/tree/1.0.0" + }, + "time": "2019-01-08T18:20:26+00:00" + }, { "name": "psr/log", "version": "3.0.2", @@ -5112,6 +4880,77 @@ ], "time": "2026-08-25T14:18:42+00:00" }, + { + "name": "symfony/deprecation-contracts", + "version": "v3.8.1", + "source": { + "type": "git", + "url": "https://github.com/symfony/deprecation-contracts.git", + "reference": "feb1edf4e546af3b85c5caebe8359a20db230ca3" + }, + "dist": { + "type": "zip", + "url": "https://api.github.com/repos/symfony/deprecation-contracts/zipball/feb1edf4e546af3b85c5caebe8359a20db230ca3", + "reference": "feb1edf4e546af3b85c5caebe8359a20db230ca3", + "shasum": "" + }, + "require": { + "php": ">=8.1" + }, + "type": "library", + "extra": { + "thanks": { + "url": "https://github.com/symfony/contracts", + "name": "symfony/contracts" + }, + "branch-alias": { + "dev-main": "3.8-dev" + } + }, + "autoload": { + "files": [ + "function.php" + ] + }, + "notification-url": "https://packagist.org/downloads/", + "license": [ + "MIT" + ], + "authors": [ + { + "name": "Nicolas Grekas", + "email": "p@tchwork.com" + }, + { + "name": "Symfony Community", + "homepage": "https://symfony.com/contributors" + } + ], + "description": "A generic function and convention to trigger deprecation notices", + "homepage": "https://symfony.com", + "support": { + "source": "https://github.com/symfony/deprecation-contracts/tree/v3.8.1" + }, + "funding": [ + { + "url": "https://symfony.com/sponsor", + "type": "custom" + }, + { + "url": "https://github.com/fabpot", + "type": "github" + }, + { + "url": "https://github.com/nicolas-grekas", + "type": "github" + }, + { + "url": "https://tidelift.com/funding/github/packagist/symfony/symfony", + "type": "tidelift" + } + ], + "time": "2026-09-16T14:15:10+00:00" + }, { "name": "symfony/filesystem", "version": "v8.1.6", diff --git a/docs/field-mapping.md b/docs/field-mapping.md index cd9c236..098ae60 100644 --- a/docs/field-mapping.md +++ b/docs/field-mapping.md @@ -99,13 +99,13 @@ The normalizer converts the object to a storable value and back. ```php use Patchlevel\Hydrator\Normalizer\InvalidType; -use Patchlevel\Hydrator\Normalizer\NormalizerWithContext; +use Patchlevel\Hydrator\Normalizer\Normalizer; #[Attribute(Attribute::TARGET_CLASS)] -final class SkillNormalizer implements NormalizerWithContext +final class SkillNormalizer implements Normalizer { /** @param array $context */ - public function normalize(mixed $value, array $context = []): mixed + public function normalize(mixed $value, array $context): mixed { if ($value === null) { return null; @@ -119,7 +119,7 @@ final class SkillNormalizer implements NormalizerWithContext } /** @param array $context */ - public function denormalize(mixed $value, array $context = []): mixed + public function denormalize(mixed $value, array $context): mixed { if ($value === null) { return null; diff --git a/src/Hydrator/DocumentHydrator.php b/src/Hydrator/DocumentHydrator.php index ef8cae4..8dafc5a 100644 --- a/src/Hydrator/DocumentHydrator.php +++ b/src/Hydrator/DocumentHydrator.php @@ -5,21 +5,23 @@ namespace Patchlevel\ODM\Hydrator; use Patchlevel\Hydrator\ClassNotSupported; -use Patchlevel\Hydrator\HydratorWithContext; +use Patchlevel\Hydrator\Hydrator; use Patchlevel\ODM\Metadata\DocumentMetadata; use function array_keys; use function array_values; +use function is_array; use function is_string; -final class DocumentHydrator implements HydratorWithContext +/** @internal */ +final class DocumentHydrator { private const ID_FIELD_NAME = '_id'; private string|null $fieldNameOverride; public function __construct( - private readonly HydratorWithContext $hydrator, + private readonly Hydrator $hydrator, private readonly DocumentMetadata $documentMetadata, ) { $this->fieldNameOverride = $this->documentMetadata->fields[$this->documentMetadata->idProperty]->fieldNameOverride; @@ -28,7 +30,6 @@ public function __construct( /** * @param class-string $class * @param array $data - * @param array $context * * @return T * @@ -36,7 +37,7 @@ public function __construct( * * @template T of object */ - public function hydrate(string $class, array $data, array $context = []): object + public function hydrate(string $class, array $data): object { if ($this->fieldNameOverride) { $data[$this->fieldNameOverride] = $data[self::ID_FIELD_NAME]; @@ -67,17 +68,24 @@ public function hydrate(string $class, array $data, array $context = []): object $class = $concreteClass; } - return $this->hydrator->hydrate($class, $data, $context); + return $this->hydrator->hydrate($class, $data); } /** - * @param array $context - * * @return array + * + * @throws DocumentNotExtractable */ - public function extract(object $object, array $context = []): array + public function extract(object $object): array { - $data = $this->hydrator->extract($object, $context); + $extracted = $this->hydrator->extract($object); + + if (!is_array($extracted)) { + throw new DocumentNotExtractable($object::class, $extracted); + } + + /** @var array $data */ + $data = $extracted; if ($this->fieldNameOverride) { $data[self::ID_FIELD_NAME] = $data[$this->fieldNameOverride]; diff --git a/src/Hydrator/DocumentNotExtractable.php b/src/Hydrator/DocumentNotExtractable.php new file mode 100644 index 0000000..eb430c9 --- /dev/null +++ b/src/Hydrator/DocumentNotExtractable.php @@ -0,0 +1,23 @@ +hydrator = new DocumentHydrator($hydrator, $metadata); $this->collection = $this->database->selectCollection($this->metadata->collection); diff --git a/src/Repository/MongoDBRepositoryManager.php b/src/Repository/MongoDBRepositoryManager.php index d82c6b4..3e4fe00 100644 --- a/src/Repository/MongoDBRepositoryManager.php +++ b/src/Repository/MongoDBRepositoryManager.php @@ -5,7 +5,7 @@ namespace Patchlevel\ODM\Repository; use MongoDB\Client; -use Patchlevel\Hydrator\HydratorWithContext; +use Patchlevel\Hydrator\Hydrator; use Patchlevel\Hydrator\StackHydrator; use Patchlevel\ODM\Metadata\AttributeDocumentMetadataFactory; use Patchlevel\ODM\Metadata\DocumentMetadataFactory; @@ -19,7 +19,7 @@ final class MongoDBRepositoryManager implements RepositoryManager public function __construct( private readonly Client $client, private readonly DocumentMetadataFactory $metadataFactory, - private readonly HydratorWithContext $hydrator, + private readonly Hydrator $hydrator, private readonly string $defaultDatabase = 'default', ) { } diff --git a/src/Repository/RangoRepository.php b/src/Repository/RangoRepository.php index 79018b8..59279a6 100644 --- a/src/Repository/RangoRepository.php +++ b/src/Repository/RangoRepository.php @@ -4,7 +4,7 @@ namespace Patchlevel\ODM\Repository; -use Patchlevel\Hydrator\HydratorWithContext; +use Patchlevel\Hydrator\Hydrator; use Patchlevel\ODM\Hydrator\DocumentHydrator; use Patchlevel\ODM\Metadata\DocumentMetadata; use Patchlevel\Rango\Collection; @@ -31,7 +31,7 @@ public function __construct( private Database $database, private DocumentMetadata $metadata, - HydratorWithContext $hydrator, + Hydrator $hydrator, ) { $this->hydrator = new DocumentHydrator($hydrator, $metadata); $this->collection = $this->database->getCollection($this->metadata->collection); diff --git a/src/Repository/RangoRepositoryManager.php b/src/Repository/RangoRepositoryManager.php index b3f8be2..4d5f727 100644 --- a/src/Repository/RangoRepositoryManager.php +++ b/src/Repository/RangoRepositoryManager.php @@ -4,7 +4,7 @@ namespace Patchlevel\ODM\Repository; -use Patchlevel\Hydrator\HydratorWithContext; +use Patchlevel\Hydrator\Hydrator; use Patchlevel\Hydrator\StackHydrator; use Patchlevel\ODM\Metadata\AttributeDocumentMetadataFactory; use Patchlevel\ODM\Metadata\DocumentMetadataFactory; @@ -19,7 +19,7 @@ final class RangoRepositoryManager implements RepositoryManager public function __construct( private readonly Client $client, private readonly DocumentMetadataFactory $metadataFactory, - private readonly HydratorWithContext $hydrator, + private readonly Hydrator $hydrator, private readonly string $defaultDatabase = 'public', ) { } diff --git a/tests/Integration/Fixtures/SkillNormalizer.php b/tests/Integration/Fixtures/SkillNormalizer.php index 7991ae2..396f94e 100644 --- a/tests/Integration/Fixtures/SkillNormalizer.php +++ b/tests/Integration/Fixtures/SkillNormalizer.php @@ -6,15 +6,15 @@ use Attribute; use Patchlevel\Hydrator\Normalizer\InvalidType; -use Patchlevel\Hydrator\Normalizer\NormalizerWithContext; +use Patchlevel\Hydrator\Normalizer\Normalizer; use function is_string; #[Attribute(Attribute::TARGET_CLASS)] -final class SkillNormalizer implements NormalizerWithContext +final class SkillNormalizer implements Normalizer { /** @param array $context */ - public function normalize(mixed $value, array $context = []): mixed + public function normalize(mixed $value, array $context): mixed { if ($value === null) { return null; @@ -28,7 +28,7 @@ public function normalize(mixed $value, array $context = []): mixed } /** @param array $context */ - public function denormalize(mixed $value, array $context = []): mixed + public function denormalize(mixed $value, array $context): mixed { if ($value === null) { return null; diff --git a/tests/Unit/Fixtures/SkillNormalizer.php b/tests/Unit/Fixtures/SkillNormalizer.php index 8793df0..c6ab1b8 100644 --- a/tests/Unit/Fixtures/SkillNormalizer.php +++ b/tests/Unit/Fixtures/SkillNormalizer.php @@ -6,15 +6,15 @@ use Attribute; use Patchlevel\Hydrator\Normalizer\InvalidType; -use Patchlevel\Hydrator\Normalizer\NormalizerWithContext; +use Patchlevel\Hydrator\Normalizer\Normalizer; use function is_string; #[Attribute(Attribute::TARGET_CLASS)] -final class SkillNormalizer implements NormalizerWithContext +final class SkillNormalizer implements Normalizer { /** @param array $context */ - public function normalize(mixed $value, array $context = []): mixed + public function normalize(mixed $value, array $context): mixed { if ($value === null) { return null; @@ -28,7 +28,7 @@ public function normalize(mixed $value, array $context = []): mixed } /** @param array $context */ - public function denormalize(mixed $value, array $context = []): mixed + public function denormalize(mixed $value, array $context): mixed { if ($value === null) { return null; diff --git a/tests/Unit/Hydrator/DocumentHydratorTest.php b/tests/Unit/Hydrator/DocumentHydratorTest.php index d159cb5..c96699a 100644 --- a/tests/Unit/Hydrator/DocumentHydratorTest.php +++ b/tests/Unit/Hydrator/DocumentHydratorTest.php @@ -4,10 +4,13 @@ namespace Patchlevel\ODM\Tests\Unit\Hydrator; +use Patchlevel\Hydrator\Hydrator; use Patchlevel\Hydrator\StackHydrator; use Patchlevel\ODM\Hydrator\DocumentHydrator; +use Patchlevel\ODM\Hydrator\DocumentNotExtractable; use Patchlevel\ODM\Hydrator\UnknownDiscriminatorValue; use Patchlevel\ODM\Metadata\AttributeDocumentMetadataFactory; +use Patchlevel\ODM\Metadata\DocumentMetadata; use Patchlevel\ODM\Metadata\StackHydratorFieldMappingResolver; use Patchlevel\ODM\Tests\Unit\Fixtures\Image; use Patchlevel\ODM\Tests\Unit\Fixtures\Media; @@ -17,17 +20,17 @@ #[CoversClass(DocumentHydrator::class)] #[CoversClass(UnknownDiscriminatorValue::class)] +#[CoversClass(DocumentNotExtractable::class)] final class DocumentHydratorTest extends TestCase { + private StackHydrator $stackHydrator; + private DocumentHydrator $hydrator; protected function setUp(): void { - $stackHydrator = new StackHydrator(); - $metadata = (new AttributeDocumentMetadataFactory(new StackHydratorFieldMappingResolver($stackHydrator))) - ->metadata(Media::class); - - $this->hydrator = new DocumentHydrator($stackHydrator, $metadata); + $this->stackHydrator = new StackHydrator(); + $this->hydrator = new DocumentHydrator($this->stackHydrator, $this->metadata()); } public function testExtractWritesTheDiscriminatorValue(): void @@ -63,4 +66,36 @@ public function testHydrateWithAnUnmappedDiscriminatorValueFails(): void $this->hydrator->hydrate(Media::class, ['_id' => 'm-1', 'title' => 'Picture', '_type' => 'audio']); } + + public function testExtractFailsIfTheHydratorDoesNotReturnAnArray(): void + { + $hydrator = new DocumentHydrator( + new class implements Hydrator { + /** @param array $context */ + public function hydrate(string $class, mixed $data, array $context = []): object + { + return new $class(); + } + + /** @param array $context */ + public function extract(object $object, array $context = []): mixed + { + return 'm-1'; + } + }, + $this->metadata(), + ); + + $this->expectException(DocumentNotExtractable::class); + $this->expectExceptionMessage('The hydrator returned "string" instead of an array for the document "' . Image::class . '".'); + + $hydrator->extract(new Image('m-1', 'Picture', 800)); + } + + /** @return DocumentMetadata */ + private function metadata(): DocumentMetadata + { + return (new AttributeDocumentMetadataFactory(new StackHydratorFieldMappingResolver($this->stackHydrator))) + ->metadata(Media::class); + } } From d0aebddec4a0dbdd286ae0bbb9d4342f85b2163a Mon Sep 17 00:00:00 2001 From: David Badura Date: Sat, 7 Nov 2026 12:04:46 +0100 Subject: [PATCH 4/4] Add the upgrade guide for 2.0 Covers the switch to hydrator 2 for custom normalizers, custom hydrators and the DocumentHydrator. --- docs/UPGRADE-2.0.md | 137 ++++++++++++++++++++++++++++++++++++++++++++ docs/project.json | 3 +- 2 files changed, 139 insertions(+), 1 deletion(-) create mode 100644 docs/UPGRADE-2.0.md diff --git a/docs/UPGRADE-2.0.md b/docs/UPGRADE-2.0.md new file mode 100644 index 0000000..fe787e7 --- /dev/null +++ b/docs/UPGRADE-2.0.md @@ -0,0 +1,137 @@ +--- +searchable: false +--- +# Upgrade 2.0 + +## Hydrator + +The ODM now requires `patchlevel/hydrator` 2.1.1 or newer. Most changes come from the hydrator itself, so go through +the [hydrator upgrade guide](https://github.com/patchlevel/hydrator/blob/2.0.0/UPGRADE-2.0.md) for your +normalizers, hydrator setup and encryption attributes. The sections below cover what affects the ODM directly. + +### Custom normalizers + +The `NormalizerWithContext` interface has been removed. Every normalizer now implements `Normalizer`, whose +`normalize()` and `denormalize()` methods always receive an `array $context`. + +before: + +```php +use Patchlevel\Hydrator\Normalizer\InvalidType; +use Patchlevel\Hydrator\Normalizer\NormalizerWithContext; + +#[Attribute(Attribute::TARGET_CLASS)] +final class SkillNormalizer implements NormalizerWithContext +{ + /** @param array $context */ + public function normalize(mixed $value, array $context = []): mixed + { + if (!$value instanceof Skill) { + throw new InvalidType(); + } + + return $value->value; + } + + /** @param array $context */ + public function denormalize(mixed $value, array $context = []): mixed + { + if (!is_string($value)) { + throw new InvalidType(); + } + + return new Skill($value); + } +} +``` +after: + +```php +use Patchlevel\Hydrator\Normalizer\InvalidType; +use Patchlevel\Hydrator\Normalizer\Normalizer; + +#[Attribute(Attribute::TARGET_CLASS)] +final class SkillNormalizer implements Normalizer +{ + /** @param array $context */ + public function normalize(mixed $value, array $context): mixed + { + if (!$value instanceof Skill) { + throw new InvalidType(); + } + + return $value->value; + } + + /** @param array $context */ + public function denormalize(mixed $value, array $context): mixed + { + if (!is_string($value)) { + throw new InvalidType(); + } + + return new Skill($value); + } +} +``` +### Custom hydrators + +The repository managers and repositories now take a `Patchlevel\Hydrator\Hydrator` instead of a +`Patchlevel\Hydrator\HydratorWithContext`. The methods of `Hydrator` work on `mixed` data, so adapt the +signatures of your own hydrator. For documents, `extract()` still has to return an array, otherwise the +repository throws `Patchlevel\ODM\Hydrator\DocumentNotExtractable`. + +before: + +```php +use Patchlevel\Hydrator\HydratorWithContext; + +final class LoggingHydrator implements HydratorWithContext +{ + public function __construct( + private readonly HydratorWithContext $hydrator, + ) { + } + + /** @param array $context */ + public function hydrate(string $class, array $data, array $context = []): object + { + return $this->hydrator->hydrate($class, $data, $context); + } + + /** @param array $context */ + public function extract(object $object, array $context = []): array + { + return $this->hydrator->extract($object, $context); + } +} +``` +after: + +```php +use Patchlevel\Hydrator\Hydrator; + +final class LoggingHydrator implements Hydrator +{ + public function __construct( + private readonly Hydrator $hydrator, + ) { + } + + /** @param array $context */ + public function hydrate(string $class, mixed $data, array $context = []): object + { + return $this->hydrator->hydrate($class, $data, $context); + } + + /** @param array $context */ + public function extract(object $object, array $context = []): mixed + { + return $this->hydrator->extract($object, $context); + } +} +``` +### DocumentHydrator + +`Patchlevel\ODM\Hydrator\DocumentHydrator` is internal now and no longer implements the `Hydrator` +interface. Load and store documents through the repository instead of using it directly. diff --git a/docs/project.json b/docs/project.json index 0cebeb5..ecc0f7d 100644 --- a/docs/project.json +++ b/docs/project.json @@ -17,6 +17,7 @@ { "title": "Encryption", "file": "encryption.md" }, { "title": "Databases", "file": "databases.md" } ] - } + }, + { "title": "Upgrade from 1.x", "file": "UPGRADE-2.0.md" } ] }