Attributes Laravel Package

Getting Started

Start by requiring the package via Composer:

composer require spiral/attributes

Then, use the Reader class to scan attributes on classes, methods, properties, or parameters. The core pattern is simple:

use Spiral\Attributes\Reader;

$reader = new Reader();
$reflection = new ReflectionClass(MyClass::class);
$attributes = $reader->getClassAttributes($reflection);

For first use, inspect a simple class with an attribute (e.g., #[Route('/api')]) to verify attribute discovery works—check that getClassAttributes() returns an array of AttributeMetadata instances. This is the foundation for most integrations.

Implementation Patterns

• Centralized Annotation Processing: Use Reader in service providers or middleware to scan controllers, jobs, or repositories for custom attributes (e.g., #[Cacheable], #[Permission]), then trigger logic based on metadata.
• Dependency-Aware Instantiation: When attributes require dependencies (e.g., constructor injection), use $reader->getAttribute($reflection, Attribute::class, $container)—this resolves constructor parameters via a PSR-11 container.
• Bulk Scanning: Scan multiple classes (e.g., in a src/Actions/ directory) with reader->iterateClassAttributes() for batch configuration or route building.
• Attribute Groups: Group attributes by target using filterByTarget() or filterByAttributeClass() to handle #[ValidationRule(...)] on properties differently than on parameters.
• Lazy Loading: Cache attribute metadata in production (e.g., with symfony/cache) by serializing AttributeMetadata objects—Reader supports __serialize()/__unserialize() out of the box.

Gotchas and Tips

• PHP Version Sensitivity: Requires PHP 8.0+; ensure your project targets ≥8.1 for full feature parity (e.g., class-level #[AllowDynamicProperties] won’t be captured on older versions).
• Multiple Annotations with Same Target: If using multiple attributes of the same type (e.g., #[Validate(...)] #[Validate(...)]), use reader->getAllAttributes() instead of getAttribute() to avoid overwrites.
• Target Validation: Verify attribute targets match expectations (e.g., #[Target(TARGET_CLASS)])—mismatches silently return empty results. Use Attribute::getTargets() to debug.
• Container Dependency Injection: When passing a PSR-11 container to getAttribute(), ensure all constructor parameters of the attribute class are resolvable; otherwise, throw a ContainerExceptionInterface.
• Extending Behavior: Override Reader behavior by extending it and injecting custom ResolverInterface implementations for advanced constructor resolution (e.g., non-service parameters or computed defaults).
• Caveat with Inheritance: By default, attribute scanning is shallow (only direct class attributes). Use reader->getClassAttributes($reflection, true) with the second parameter true to include inherited attributes.