Metadata Laravel Package

Getting Started

Start by installing the package via Composer:

composer require jms/metadata

The core abstraction is Metadata\MetadataFactory, which retrieves structured metadata for classes, methods, and properties. The first step is typically setting up a DriverChain to aggregate metadata sources—like annotations, YAML, XML, or PHP configuration files. For example, to begin reading from YAML files:

use Metadata\Driver\YamlDriver;
use Metadata\Driver\DriverChain;
use Metadata\MetadataFactory;

$chain = new DriverChain([
    new YamlDriver('/path/to/metadata'),
]);

$factory = new MetadataFactory($chain);
$metadata = $factory->getMetadataForClass(MyClass::class);

Begin with simple use cases: inspecting class-level metadata (e.g., serialization groups, route options) or enriching DTOs with runtime-configurable behavior. Check the MetadataFactory return value—it will be a ClassMetadata instance holding method and property metadata arrays if defined.

Implementation Patterns

Metadata is often used as a foundational layer for higher-level frameworks (e.g., Serializer, Doctrine, security annotations). Common patterns include:

• Custom Driver for External Configs: Extend AbstractFileDriver to load metadata from custom sources (e.g., environment variables, database records, or remote APIs). This is useful when metadata must be toggled without redeploying code.
• Metadata Decoration/Proxying: Wrap the MetadataFactory in a caching or profiling decorator (e.g., using TraceableFileLocatorInterface for debugging file resolution).
• Late-Bound Properties: Use PropertyMetadata::getExtra() to attach arbitrary runtime data—like form field hints or validation rules—then inject those into UI builders or formatters.
• Hybrid Annotation + Config Drivers: Combine AnnotationDriver with YamlDriver for flexibility: use annotations for convenience and YAML for ops-friendly overrides.
• Lazy Loading: Only load metadata on demand (e.g., per controller or command) to reduce boot-time overhead, especially with large class trees.

Integration with PSR-11 containers is seamless—pass your container to MetadataFactory via its constructor to resolve driver dependencies dynamically.

Gotchas and Tips

• Cache Permissions & Read-Only Filesystems: The library auto-creates cache directories (2.5.0+), but ensure the cache path is writable or explicitly configure a ReadOnlyCache. Failures often surface as cryptic rename() errors on Windows—upgrade to latest 2.x to benefit from robust fallback handling.
• Performance Gotcha: In 1.x, missing metadata for a class always triggered a cache miss. From 1.5+, NullMetadata is cached—ensure you’re not re-querying the same class name repeatedly in hot loops. Profile with TraceableFileLocatorInterface.
• Reflection Delay: MethodMetadata and PropertyMetadata lazily initialize their internal Reflection* objects. Avoid calling getReflection() unnecessarily—properties/methods already parsed in ClassMetadata are often enough.
• Namespace Resolution: For classes without namespaces or defined in global scope, ensure your file locator can resolve them. See GitHub issue #5 for related fixes.
• Anonymouse Class Support: Added in 2.2.0—cache must be enabled to avoid runtime reflection on anonymous classes, which would otherwise break cold-start scenarios.
• Next-Gen Compatibility: Avoid direct use of deprecated Doctrine Cache adapters (deprecated in 2.9.0); prefer PSR-6/PSR-16 or PsrCacheAdapter. PHP 8.1+ compatibility is handled—don’t override setAccessible() manually.