Skip to content

Fix array shapes, nullable collection items and inherited metadata in 1.x - #244

Merged
DavidBadura merged 8 commits into
1.24.xfrom
normalizer-fixes-1x
Nov 6, 2026
Merged

DavidBadura merged 8 commits into
1.24.xfrom
normalizer-fixes-1x

Conversation

@DavidBadura

Copy link
Copy Markdown
Member

Backports the fixes from #241, #242 and the lazy part of #243 that also apply to 1.x, plus one bug that only exists here. The class normalizer fixes from #239, #240 and the ObjectMap part of #243 are not needed, since 1.x has no class level normalizers.

  • ArrayShapeNormalizer keeps keys without a normalizer and keys holding null instead of dropping them.
  • Collections with nullable items (list<?Skill>, array<string, ?Status>, list<?DateTimeImmutable>) get a normalizer again, plus the handleType fix for explicit map keys missing in the docblock shape and the simplification of the duplicate unwrap code.
  • mergeMetadata() had its parameters swapped, so a parent's #[Lazy] won over the child's.
  • Inherited #[PostHydrate]/#[PreExtract] methods ran once per class level. Each hook now runs once, as the method PHP would call, so an override runs as the child's version even without repeating the attribute.
  • Readme examples that could not work or did not parse.

Release note: collections with nullable items of dates, date intervals, time zones or objects without public properties were stored raw before and can no longer be hydrated from that old data (enums and public property objects keep the same format). Normalizers now get null for null values inside array shapes, shape output follows the input key order, and metadata cached with the PSR-6 or PSR-16 factories keeps the old result until the cache is cleared.

Merge-up into 2.0.x needs care in a few places:

  • ArrayShapeNormalizer: the auto-merged lines around the conflict end in return $value;, so the hunk must write to $value[$field], not $result[$field] (2.1.x already has the right code from Keep keys without a normalizer in array shapes #241).
  • AttributeMetadataFactory::mergeMetadata(): the signature merges to ($child, $parent) while the 2.x body still uses the swapped names. Take the body from Don't use the ObjectMapNormalizer as a class normalizer #243 and drop the 1.x only methods (mergeCallbacks, getSubjectIdField, getPersonalData, validate).
  • Delete tests/Unit/Fixture/ParentDtoWithHooks.php with its baseline entry and MetadataHydratorTest, keep the 2.x readme, regenerate the baseline. The remaining test conflicts just keep both sides.

ArrayShapeNormalizer only returned the keys it had an inner normalizer for,
so every other key of the shape was silently dropped on extract and hydrate.
Keys holding null were dropped too because of isset(). The normalizer now
works on the given array and only converts the keys it has a normalizer for,
null included, and keeps everything else as it is, like ArrayNormalizer and
plain arrays do.
The collection branch unwrapped the nullable item type from the collection
itself instead of from the item type, so collections like list<?Skill> got no
normalizer at all and their items were passed through as raw objects.
An explicit ArrayShapeNormalizer map can contain keys that the property's
docblock shape doesn't know. handleType read those keys anyway and raised
undefined key warnings. Such fields are now left alone, like the whole map is
when the property type isn't an array shape.
The collection and array shape branches unwrapped nullable item types and
looked for a class normalizer before recursing, although inferNormalizerByType
does both on its own. Dropping the duplicate removes the place where the
nullable item bug came from. The shape branch is now also covered in the
metadata factory test.
The parameter names of mergeMetadata() were swapped relative to the call site,
so the lazy flag of the parent took precedence over the child's. A class with
#[Lazy(false)] extending a #[Lazy] class was still hydrated lazily. Everything
else keeps its current order: properties, callbacks and the data subject id of
the child still come first.
getMethods() already returns the public and protected methods a class inherits,
and mergeMetadata() added the parent's callbacks on top, so an inherited
#[PostHydrate] or #[PreExtract] method was called twice. An overridden one ran
as the child's version and then again as the parent's, because the parent's
reflection method was invoked directly. The merge now resolves every callback to
the method PHP would call on the child and keeps it once. An override runs as
the child's version, also when it doesn't repeat the attribute. Private methods
of the parent are not inherited and stay as they are.
The array and array shape examples used #[ArrayNormalizer] and
#[ArrayShapeNormalizer] without arguments, which fails because both constructors
require the inner normalizers. In these cases the normalizer is inferred from
the docblock, so the attribute is dropped and the text says so. A few other
examples had typos that made them invalid PHP, like a misspelled class name,
missing semicolons and a match arm written as a case.
Normalizers get null for nullable properties and, since the array shape fix,
for null values in shapes as well, so the example should not reject it.
@DavidBadura DavidBadura added this to the 1.24.4 milestone Nov 6, 2026
@DavidBadura DavidBadura added the bug Something isn't working label Nov 6, 2026
@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown

Hello 👋

here is the most recent benchmark result:

HydratorBench
=============

+-------------------------------+-------------------+------------------+-----------------+------------+
|                               | time (kde mode)                      | memory                       |
+-------------------------------+-------------------+------------------+-----------------+------------+
| subject                       | Tag: <current>    | Tag: base        | Tag: <current>  | Tag: base  |
+-------------------------------+-------------------+------------------+-----------------+------------+
| benchHydrate1Object ()        | 5.000μs (±0.00%)  | 3.800μs (±0.00%) | 2.823mb         | 3.271mb    |
| benchExtract1Object ()        | 56.800μs (±0.00%) | 4.000μs (±0.00%) | 2.823mb         | 3.271mb    |
| benchHydrate1000Objects ()    | 2.709ms (±0.00%)  | 2.650ms (±0.00%) | 2.937mb         | 3.403mb    |
| benchExtract1000Objects ()    | 2.542ms (±0.00%)  | 2.514ms (±0.00%) | 2.863mb         | 3.307mb    |
| benchHydrate1000000Objects () | 1.507s (±0.00%)   | 1.541s (±0.00%)  | 2.937mb         | 2.938mb    |
| benchExtract1000000Objects () | 1.483s (±0.00%)   | 1.412s (±0.00%)  | 2.863mb         | 2.840mb    |
+-------------------------------+-------------------+------------------+-----------------+------------+

HydratorWithCryptographyBench
=============================

+-------------------------------+-------------------+-------------------+-----------------+------------+
|                               | time (kde mode)                       | memory                       |
+-------------------------------+-------------------+-------------------+-----------------+------------+
| subject                       | Tag: <current>    | Tag: base         | Tag: <current>  | Tag: base  |
+-------------------------------+-------------------+-------------------+-----------------+------------+
| benchHydrate1Object ()        | 8.200μs (±0.00%)  | 90.400μs (±0.00%) | 2.871mb         | 2.889mb    |
| benchExtract1Object ()        | 11.000μs (±0.00%) | 10.800μs (±0.00%) | 2.871mb         | 2.805mb    |
| benchHydrate1000Objects ()    | 4.973ms (±0.00%)  | 4.691ms (±0.00%)  | 3.084mb         | 3.084mb    |
| benchExtract1000Objects ()    | 6.317ms (±0.00%)  | 6.118ms (±0.00%)  | 2.982mb         | 2.986mb    |
| benchHydrate1000000Objects () | 2.710s (±0.00%)   | 2.801s (±0.00%)   | 3.084mb         | 3.084mb    |
| benchExtract1000000Objects () | 4.130s (±0.00%)   | 4.132s (±0.00%)   | 2.982mb         | 2.986mb    |
+-------------------------------+-------------------+-------------------+-----------------+------------+

StackHydratorBench
==================

+-------------------------------+--------------------+-------------------+-----------------+------------+
|                               | time (kde mode)                        | memory                       |
+-------------------------------+--------------------+-------------------+-----------------+------------+
| subject                       | Tag: <current>     | Tag: base         | Tag: <current>  | Tag: base  |
+-------------------------------+--------------------+-------------------+-----------------+------------+
| benchHydrate1Object ()        | 109.000μs (±0.00%) | 3.800μs (±0.00%)  | 2.773mb         | 2.772mb    |
| benchExtract1Object ()        | 3.600μs (±0.00%)   | 63.200μs (±0.00%) | 2.772mb         | 2.772mb    |
| benchHydrate1000Objects ()    | 2.676ms (±0.00%)   | 2.709ms (±0.00%)  | 3.019mb         | 3.019mb    |
| benchExtract1000Objects ()    | 2.321ms (±0.00%)   | 2.338ms (±0.00%)  | 2.942mb         | 2.942mb    |
| benchHydrate1000000Objects () | 1.520s (±0.00%)    | 1.531s (±0.00%)   | 3.020mb         | 3.020mb    |
| benchExtract1000000Objects () | 1.428s (±0.00%)    | 1.492s (±0.00%)   | 2.942mb         | 2.942mb    |
+-------------------------------+--------------------+-------------------+-----------------+------------+

StackHydratorWithCryptographyBench
==================================

+-------------------------------+-------------------+------------------+-----------------+------------+
|                               | time (kde mode)                      | memory                       |
+-------------------------------+-------------------+------------------+-----------------+------------+
| subject                       | Tag: <current>    | Tag: base        | Tag: <current>  | Tag: base  |
+-------------------------------+-------------------+------------------+-----------------+------------+
| benchHydrate1Object ()        | 39.600μs (±0.00%) | 5.800μs (±0.00%) | 2.799mb         | 2.799mb    |
| benchExtract1Object ()        | 5.200μs (±0.00%)  | 5.600μs (±0.00%) | 2.799mb         | 2.799mb    |
| benchHydrate1000Objects ()    | 3.809ms (±0.00%)  | 3.872ms (±0.00%) | 3.090mb         | 3.090mb    |
| benchExtract1000Objects ()    | 3.531ms (±0.00%)  | 3.608ms (±0.00%) | 3.132mb         | 2.979mb    |
| benchHydrate1000000Objects () | 2.219s (±0.00%)   | 2.253s (±0.00%)  | 3.090mb         | 3.090mb    |
| benchExtract1000000Objects () | 2.155s (±0.00%)   | 2.192s (±0.00%)  | 3.132mb         | 2.976mb    |
+-------------------------------+-------------------+------------------+-----------------+------------+

HydratorWithLazyBench
=====================

+------------------------------------------+--------------------+--------------------+-----------------+------------+
|                                          | time (kde mode)                         | memory                       |
+------------------------------------------+--------------------+--------------------+-----------------+------------+
| subject                                  | Tag: <current>     | Tag: base          | Tag: <current>  | Tag: base  |
+------------------------------------------+--------------------+--------------------+-----------------+------------+
| benchHydrate1Object ()                   | 1.000μs (±0.00%)   | 0.600μs (±0.00%)   | 2.825mb         | 2.772mb    |
| benchHydrate1ObjectTriggerInit ()        | 5.400μs (±0.00%)   | 4.600μs (±0.00%)   | 2.825mb         | 2.772mb    |
| benchHydrate1000Objects ()               | 444.000μs (±0.00%) | 442.667μs (±0.00%) | 2.825mb         | 2.812mb    |
| benchHydrate1000ObjectsTriggerInit ()    | 3.344ms (±0.00%)   | 3.643ms (±0.00%)   | 2.937mb         | 2.936mb    |
| benchHydrate1000000Objects ()            | 302.443ms (±0.00%) | 295.588ms (±0.00%) | 2.825mb         | 2.812mb    |
| benchHydrate1000000ObjectsTriggerInit () | 2.213s (±0.00%)    | 2.220s (±0.00%)    | 2.937mb         | 2.936mb    |
+------------------------------------------+--------------------+--------------------+-----------------+------------+

This comment gets update everytime a new commit comes in!

@DavidBadura
DavidBadura merged commit 25b84e5 into 1.24.x Nov 6, 2026
14 of 16 checks passed
@DavidBadura
DavidBadura deleted the normalizer-fixes-1x branch November 6, 2026 20:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants