Download the PHP package oihana/php-reflect without Composer

Oihana PHP - Reflect

Lightweight reflection and hydration helpers for modern PHP, part of the Oihana PHP ecosystem.

It provides:

• Friendly wrappers around PHP's Reflection API
• Array-to-object hydration with attribute-based mapping
• Utilities to expose public properties as arrays
• Simple constant “enums” helpers
• A compact Version value object

📚 Documentation

Full documentation: https://bcommebois.github.io/oihana-php-reflect

📦 Installation

Requires PHP 8.4+

✨ Features

Reflection helpers

• List constants, methods, properties with visibility filters
• Inspect method parameters: type, default, nullable, optional, variadic
• Inspect classes/properties: hasMethod, hasProperty, propertyType, namespace (union types rendered as A|B, intersection as A&B)
• Read instantiated attributes: classAttributes, propertyAttributes, methodAttributes (optionally filtered by attribute class)
• Describe any callable’s parameters (describeCallableParameters)
• Cached ReflectionClass instances

Hydration

• Instantiate and hydrate objects from associative arrays (recursively)
• Supports union types and nullability
• Attribute-based mapping:
  • #[HydrateKey('source_key')] to rename incoming keys (accepts several fallback keys: #[HydrateKey('user_name', 'username')] — first present wins)
  • #[HydrateWith(Foo::class, Bar::class)] for arrays of objects, including polymorphism via @type/type or property-guessing
  • #[HydrateAs(Foo::class)] to override ambiguous types (object, array, mixed, unions)
  • #[Transient] (or its alias #[HydrateIgnore]) to exclude a public property from both hydration (input) and toArray() (output) — e.g. computed/derived properties
• PHPDoc @var Type[] and @var array<Type> support for array element types
• Backed enums: scalar values are resolved to enum cases via Enum::from() (single values, and arrays of enums via #[HydrateWith] or @var Enum[]). Pure (non-backed) enums have no scalar representation: hydrating one from a scalar throws an InvalidArgumentException — declare a backed enum instead
• DateTimeInterface: scalar values are resolved to date instances (string → parsed date, int → Unix timestamp). In a union with a scalar (e.g. string|DateTimeInterface), the raw value is kept unless #[HydrateAs(DateTimeImmutable::class)] forces the conversion
• Classes with a required constructor: instantiated via newInstanceWithoutConstructor() and populated from the data (a no-argument-callable constructor is still invoked normally)
• readonly and asymmetric-visibility properties (public private(set) / public protected(set), PHP 8.4): values are assigned via reflection, so they are initialized correctly (scalar coercion preserved)
• Scalar coercion: values are converted to the declared scalar type following PHP's coercive typing ('42' → int 42, 7 → string '7'); a value that cannot be coerced raises a HydrationException (independent of strict_types)
• Error handling: every hydration failure throws a single catchable HydrationException (extends InvalidArgumentException), exposing getClassName(), getPropertyName() and the original error via getPrevious() — handy to skip an invalid record when hydrating a batch/stream
• Symmetric serialization: ReflectionTrait::toArray() serializes DateTimeInterface values to ISO 8601 (overridable), and can emit #[HydrateKey] source keys (opt-in via SerializeOption) — round-trip with hydrate()
• Performance: a per-class hydration plan is cached on first use, so the data-independent reflection work (attributes, @var item types, constructor strategy, builtin types) is computed once and reused for every object of that class. The cache is in-memory, bounded by the number of hydrated classes, and needs no eviction. On nested documents this cuts hydration time by roughly a third (the deeper the nesting, the larger the gain)

Traits

• ReflectionTrait convenience layer and jsonSerializeFromPublicProperties() (with optional reduction)
• ConstantsTrait utilities over class constants: getAll, includes, enums, getConstant, validate

Value objects

• Version packs major/minor/build/revision into a 32-bit int with configurable string output

🚀 Quick start

Reflection basics

Describe any callable

Hydration: flat and nested

Hydration with attributes

Arrays of objects via PHPDoc

Polymorphic arrays with HydrateWith

Trait: ReflectionTrait

Trait: ConstantsTrait

Value object: Version

✅ Running Unit Tests

Run a specific test file:

🛠️ Generate the API Docs

We use phpDocumentor to generate the HTML docs into ./docs.

🧾 License

Licensed under the Mozilla Public License 2.0 (MPL-2.0). See LICENSE.

👤 Author

• Author: Marc ALCARAZ (aka eKameleon)
• Email: [email protected]
• Website: http://www.ooop.fr