Download the PHP package drabek-digital/hydra without Composer

Hydra 🐉

This is a serialization & deserialization & validation library with minimum dependencies to allow you easily guard the app's valuable asset - data integrity. All that in PHP using top-notch PHP 8.4 language features.

The main principles of this approach are:

• Specification of serialization & deserialization & validation via PHP attributes in the DTOs
• First pass generates a DTOs hierarchy with hydration/dehydration logic in place through normal PHP code (isset, array_key_exists, is_string, is_int, ...) and caches generated runtime for subsequent runs.
• Validation is a separate runtime flow (Validator) and is not code-generated.
• Attributes should be specified above properties only when needed (in other words native typing should be used when possible)
• There should be sane defaults for most of the situations.
• Validation & dehydration & hydration are recursive.

Limitations:

• Circular references are not supported.
• Type coercion is prevented by design.
• readonly DTOs without constructor parameters are not currently supported for hydration. Use constructor-based readonly DTOs (promoted params), or non-readonly public properties for property-only DTOs.

Naming strategy

Bidirectional way how the fields are mapped during serialization & deserialization.

• Default (1:1 mapping)
• UnderscoreCase: use when in serialized format you have underscore_case while members are named in camelCase

Also there is possibility to rename a particular field (for legacy named fields) by using Rename attribute. Rename is direction-aware: use from for hydration (input) and to for dehydration (output).

Mappers

• Scalars
  • bool
  • float
  • int
  • mixed
  • string

Special types:

• DateTimeInterface and DateTimeImmutable
• BackedEnum
• Array and lists
  • array (of anything)
  • Listof particular value type (with discriminator)
  • Map of particular key & value type (with discriminator)
• Shapes
  • Object of particular type (with discriminator)
• Custom mappers
  • CustomMapper of particular type (or your own attribute implementing MapperAttribute interface)

Validators

• Integer & float
  • Range (min, max, inclusive, exclusive) - NumberRange
• Strings
  • LengthRange (min, max) with one particular alias NonEmptyString
  • Regex - StringMatches
  • URL
• Array
  • Count (min, max)
  • Unique items (including custom comparator)
• Date & time
  • DateTimeRange (min, max, inclusive, exclusive)
• Custom

Usage

Runtime code loading and temp directory safety

Hydra executes generated PHP runtime code loaded from cache.

• FileCache stores generated code in files and loads it with require.
• Psr16CacheAdapter loads generated code from cache storage and executes it via eval().

Because generated code is executable, treat cache storage as trusted runtime surface:

• keep cache backend private to your application process,
• do not share writable cache/temp directories with untrusted actors,
• prefer app-scoped directories over generic system temp locations in production,
• clear cache after deployments that change DTO structures.

Errors handling

Hydration

Use getErrors on Failure exception to get particular instance of HydrationError which will contain

• code - any backed enum
• programmerMessage - which will describe the error in programmer understandable way for debugging & logging purposes
• key - property, array key etc... where the error is, can be string, int, bool, or null
• fullPath - full path from root towards the property, array key etc... where the error is. For example person.interests.0.name

Dehydration

Use getErrors to get particular instance of DehydrationError which will contain

• code - any backed enum
• programmerMessage - which will describe the error in programmer understandable way for debugging & logging purposes
• key - property, array key etc... where the error is, can be string, int, bool, or null
• fullPath - full path from root towards the property, array key etc... where the error is. For example person.interests.0.name

Validation

Use getErrors to get particular instance of ValidationError which will contain

• code - any backed enum
• programmerMessage - which will describe the error in programmer understandable way for debugging & logging purposes
• key - property, array key etc... where the error is, can be string, int, bool, or null
• fullPath - full path from root towards the property, array key etc... where the error is. For example person.interests.0.name

Detailed docs

• Naming strategies
• Mappers
• Validators

Potential future scope

• Serialization groups
• Lifecycle hooks
• Conditional Inclusion (SkipWhen, IncludeIf)
• Prefixed fields (PrefixedWith)