GH-73: Derive a class's mapping shape once, not per element

[magicsunday]

Fixes #73.

Per mapSingleObject() call — that is, per COLLECTION ELEMENT — the mapper re-derived through fresh reflection everything a class's declaration already fixes: the property list, the ReplaceProperty map, the constructor analysis, and per property the required check and default. Only the property type was cached. Measured with a counting extractor:

before   1 element -> 1 derivation ... 100 elements -> 100
after    any element count -> 1 per class

and 100 elements of one class dropped from 8.9 ms to 3.2 ms.

The shape

ClassMetadata (a readonly value object) holds what the declaration fixes; ClassMetadataFactory derives and memoises it per instance. That memo replaces the static $cache in unknownPropertyCollector() — the library's only global state, in a final readonly class, contradicting the project's own rule. 294 lines left JsonMapper.

Not routed through the PSR-6 pool the issue suggests: the metadata holds a ReflectionMethod, which does not survive serialisation. Deriving it is cheap once it happens once per class, and an in-memory memo is what the measured cost called for.

What review caught — three defects, all mine, two silent

An unused default was evaluated. A declared default can be an expression, and reflection evaluates it when asked for the value. Caching the resolved value per class meant a promoted new X() ran even when the payload supplied the property — and a throw from it escaped as a native error past the report.

An object default was shared across elements. The evaluated object, frozen into the metadata, was handed to every element of a collection: mutate it on one, mutate it on all. Silent shared state between objects that never met. Neither defect was covered by the then-377 tests.

Both fixed by caching the reflection handle and evaluating per call — the per-element cost the issue targets (the lookup) stays memoised; the evaluation returns to per-use. Two regression tests pin it.

The static $cache I claimed to have removed was still there — moved verbatim, static included, so the global state the change's headline was removing had survived it. Gone now.

Also, while fixing the eager evaluation, the constructor's promoted parameters are collected once per class rather than re-reflected per property — the review measured ~1.8× on a wide class with a narrow payload otherwise.

Two things the tooling caught rather than me: PHPStan found getReflectionClass() left dead by the move, and jscpd found 42 lines of helper duplication — resolved by moving what the helpers were used for (replace-null flag, default value) into the metadata, since those are declaration facts too.

Acceptance criteria

• ✅ No static cache; metadata resolved through an injectable, cacheable component (grep -rn 'static $' src/ is empty).
• ✅ Collections no longer re-reflect per element — verified with a call-counting extractor stub, one derivation per class regardless of element count.

composer ci:test green, verified by exit code: 379 tests, 1229 assertions; PHPStan max, Rector, CGL and CPD clean.

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!