Skip to content
CAI
Software that uses CAICheck a score

patchlevel/hydrator

63.2

Adequate · 9 November 2026

4k

lines of production code

PHP

primary language

7

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

What this system is

Features

Add groups extension for property selection

Introduces a new Groups extension that allows users to filter which properties are hydrated or extracted based on group names. By annotating properties with the \#\[Groups\] attribute and passing 'groups' or 'ignored\_groups' in the hydration context, users can selectively include or exclude specific fields during data transformation.

src/Extension/Groups · high confidence

Introduce Guesser component for automatic normalizer resolution

A new Guesser component has been added to automatically determine the appropriate normalizer for a given type. This includes a \BuiltInGuesser\ that handles standard PHP types like \DateTime\, \DateInterval\, and enums, a \MappedGuesser\ for explicit class-to-normalizer mappings, and a \ChainGuesser\ to combine multiple guessers. This allows the hydrator to resolve normalizers without manual configuration for common scenarios.

src/Guesser · high confidence

Introduce Upcast extension for data transformation

The new Upcast extension allows users to transform raw data before it is decoded into objects (before transform) or before it is encoded back to storage (before encoding). This is achieved via the UpcastExtension which registers UpcastMiddleware, supporting both callback-based upcasting through CallbackUpcaster and attribute-based targeting via the new UpcasterFor attribute. The Upcaster interface has been refactored to operate on ClassMetadata and return transformed data arrays rather than hydrated objects, enabling flexible data reshaping at specific points in the hydration/extraction pipeline.

src/Extension/Upcast · high confidence

Introduce extensible cipher key storage with PSR-16/PSR-6 caching support

The cryptography extension now provides a dedicated store layer for managing encryption keys, allowing applications to persist and retrieve cipher keys via a standardized interface. This includes an in-memory implementation for development or simple use cases, and decorators that wrap any existing store with PSR-16 or PSR-6 cache backends to improve performance through key caching. A new \CipherKeyNotExists\ exception is introduced to handle cases where a requested key is missing, ensuring clearer error reporting during decryption or key rotation operations.

src/Extension/Cryptography/Store · high confidence

Lifecycle extension for pre/post hydrate and extract hooks

Users can now attach static lifecycle methods to their classes using the new \#\[PreHydrate\], \#\[PostHydrate\], \#\[PreExtract\], and \#\[PostExtract\] attributes. The LifecycleExtension integrates a middleware and metadata enricher that automatically invoke these methods at the appropriate stages of the hydration and extraction process, allowing for data transformation or side effects before and after the core mapping logic.

src/Extension/Lifecycle · high confidence

New cryptography extension for transparent field encryption

The \src/Extension/Cryptography\ directory now contains a new extension that enables transparent encryption and decryption of sensitive object properties. Users can mark properties with the \SensitiveData\ attribute (optionally specifying a \subjectIdName\ and a fallback value) and identify the corresponding subject identifier field with the \DataSubjectId\ attribute. The extension uses a \CryptographyMiddleware\ to intercept hydration and extraction, encrypting values on write and decrypting them on read using the \BaseCryptographer\. The default implementation relies on OpenSSL (AES-128-GCM by default) and manages cipher keys via a \CipherKeyStore\. This change introduces a new behavioral capability for data protection within the hydrator pipeline.

src/Extension/Cryptography · high confidence

Removals

Removal of MetadataHydrator class

The \MetadataHydrator\ class has been removed from the \src/Hydrator\ directory. This class previously handled object hydration and extraction by leveraging a \MetadataFactory\ to iterate over property metadata, applying normalizers and handling type mismatches. Its removal indicates a shift in how metadata-driven hydration is implemented or consumed within the library.

src/Hydrator · high confidence

Behavioural changes

1 commit (0 fixes) modifying bin

A change to existing behaviour in bin — 1 commit, 2 files: “Keep the frontmatter of the docs when formatting the code”. Also in this area: New documentation processing scripts for PHP code extraction and injection.

bin · medium confidence · unverified

Hydrator restructured with StackHydrator and explicit exception hierarchy

The core hydration engine has been replaced by a new \StackHydrator\ that processes data through a configurable stack of middlewares, supporting lazy object instantiation via PHP 8.4 proxies. The exception system has been restructured: all error classes (such as \ArrayDataRequired\, \CircularReference\, \ClassNotSupported\, \DenormalizationFailure\, \NormalizationFailure\, \ObjectRequired\, and \TypeMismatch\) now extend \RuntimeException\ and implement the \HydratorException\ interface, replacing the previous inheritance from \HydratorException\. The builder API (\StackHydratorBuilder\) now uses an \Extension\ interface to configure middlewares, guessers, and metadata enrichers with priority-based ordering.

src · high confidence

Introduction of middleware-based hydration architecture

The hydration process has been refactored to use a middleware stack pattern, replacing the previous legacy implementation. This change introduces a new \Middleware\ interface and a \Stack\ class that manages the execution chain, allowing for modular processing during object hydration and extraction. The default \TransformMiddleware\ handles the core logic, including property mapping, normalizer integration, and circular reference detection, while a new \NoMoreMiddleware\ exception provides clearer debugging information when the middleware chain is exhausted.

src/Middleware · high confidence

Library rebranded from Event Sourcing to Hydrator with new documentation and benchmarking tools

The package has been renamed from \patchlevel/event-sourcing\ to \patchlevel/hydrator\, shifting its focus to a library for seamless object hydration. This change is accompanied by the removal of the Psalm static analysis tool in favor of PHPStan, the addition of a \phpbench.json\ configuration for performance benchmarking, and the introduction of an \UPGRADE-2.0.md\ file directing users to the new documentation. The README has been updated to reflect the new package name, features, and installation instructions.

(repo-wide) · high confidence

Metadata system overhaul with caching, inheritance support, and new attributes

The metadata layer has been significantly restructured to improve performance and flexibility. Users can now cache metadata using PSR-6 or PSR-16 implementations via new factory wrappers, and metadata objects are fully serializable for persistence. The system now supports class inheritance, automatically merging child metadata with parent metadata while throwing errors for duplicated field names. New attributes allow users to ignore properties (\\#\[Ignore\]\) or mark classes for lazy loading (\\#\[Lazy\]\). Additionally, the factory now detects property types using Symfony TypeInfo, skips static properties, and provides a mechanism to enrich metadata via the \MetadataEnricher\ interface.

src/Metadata · high confidence

Normalizers now support context passing, type inference, and hydration awareness

The normalizer API has been updated to pass a context array to normalize and denormalize methods, enabling richer data exchange during serialization. Several normalizers (Object, Enum, Array, ArrayShape) now support automatic type inference via the new TypeAwareNormalizer interface, allowing them to deduce target classes or types from PHP type hints when not explicitly configured. Additionally, normalizers can now implement HydratorAwareNormalizer to receive the parent Hydrator instance, which is required for ObjectMapNormalizer and ObjectNormalizer to perform nested hydration. New normalizers have been added for DateInterval and inline closures, while existing ones like DateTime and ArrayNormalizer have been refactored to be readonly and attribute-based.

src/Normalizer · high confidence

Test coverage

3 commits adding/updating tests in tests; Added architecture tests for exception hierarchy and class finality; Added benchmark fixtures and updated normalizer interface; Added benchmarks for StackHydrator performance; Added test fixtures for the Cryptography extension; Added unit tests for Guesser components; Added unit tests for cryptography key store implementations; Added unit tests for metadata classes and factories; Added unit tests for middleware stack and transformer middleware; Added unit tests for the Groups extension; Expanded test fixtures for normalizer and hydration features; Expanded unit test coverage for normalizer components.

Dependencies

PHP 8.5 support and dependency overhaul

The library now supports PHP 8.5 (dropping 8.1) and requires the ext-openssl extension. Core dependencies have been updated to include psr/cache, psr/simple-cache, and symfony/type-info, while dev tools like PHPUnit, PHPStan, and Infection have been upgraded to their latest major versions. The backward-compatibility check tool in the tools directory has also been updated to PHP 8.5 and roave/backward-compatibility-check v8.

(dependencies) · high confidence

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

How this codebase got here

Score

  • CAI 66 → 63 (-2.9)
  • Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.

Lenses

  • Code Health 97 → 98 (+0.5)
  • Architecture 100 → 99 (-0.5)
  • Maturity 54 → 54 (+0.0)
  • Readiness 69 → 69 (+0.0)
  • Security 68 → 56 (-11.4)
  • Performance 100 → 100 (+0.0)

Resolved (4)

  • AttributeMetadataFactory.inferNormalizerByType (cyclomatic 18) (src/Metadata/AttributeMetadataFactory.php)
  • Duplicated block (13 lines × 2) (src/Metadata/AttributeMetadataFactory.php)
  • Duplicated block (14 lines × 2) (src/Normalizer/ArrayShapeNormalizer.php)
  • Inconsistent naming for PSR-16 vs PSR-6 cache implementations. The library provides distinct classes for PSR-16 (CacheInterface) and PSR-6 (CacheItemPoolInterface) for both the CipherKeyStore and MetadataFactory. While technically distinct interfaces, the naming convention Psr16... vs Psr6... is consistent within each domain, but the API surface is fragmented. A more consistent approach might be a single CacheStoreDecorator and CacheMetadataFactory that accept a unified cache interface or use a factory pattern, reducing the number of concrete classes exposed to the user.

New (1)

  • Duplicated block (12 lines × 2) (src/Normalizer/ArrayShapeNormalizer.php)

Changes since last survey

  • 24 commits — 22 feature/other, 2 fixes

By area

  • tests/Unit — 10 commits
  • (repo) — 9 commits
  • (root) — 3 commits
  • docs/normalizer.md — 1 commit
  • src/Metadata — 1 commit

Notable commits

  • fix: Fix normalizer examples in the readme
  • fix: Merge pull request #244 from patchlevel/normalizer-fixes-1x
  • change: Cover the child winning over its parent when merging metadata
  • change: Document which array shape keys are converted
  • change: Don't use the ObjectMapNormalizer as a class normalizer
  • change: Drop the extras merge from mergeMetadata
  • change: Infer normalizers for nullable collection items
  • change: Keep keys without a normalizer in array shapes
  • change: Keep keys without a normalizer in array shapes
  • change: Let inferNormalizerByType unwrap collection and shape items itself
  • change: Let the child class win when merging inherited metadata
  • change: Let the readme normalizer example handle null
  • change: Merge branch '2.0.x' into 1.24.x-merge-up-into-2.0.x_mxZsb44N
  • change: Merge branch '2.1.x' into 2.0.x-merge-up-into-2.1.x
  • change: Merge pull request #239 from patchlevel/object-normalizer-class-normalizer
  • change: Merge pull request #240 from patchlevel/enum-class-normalizer
  • change: Merge pull request #241 from patchlevel/array-shape-keep-unmapped-keys
  • change: Merge pull request #243 from patchlevel/object-map-class-normalizer
  • change: Merge pull request #245 from patchlevel/1.24.x-merge-up-into-2.0.x_mxZsb44N
  • change: Merge pull request #247 from patchlevel/2.1.x-merge-up-into-2.2.x_FG8rfleA
  • …and 4 more

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

Survey your own repository

patchlevel/hydrator was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.

About this page

  • The score is its most recent published measurement, taken on 9 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
  • Measured at commit b045a32624f32a21e25a9cfc15951fa81c7eb79e — the exact code this score is about.
  • Scored under rubric-2026.11.2 — the same rubric and the same method as every other entry in this index.
  • Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.3+preprod-bb0cb800cd0f.