Annotations Laravel Package

Getting Started

Install via Composer: composer require zeptech/annotations. Begin by parsing class-level annotations using ReflectionClass and the Annotations constructor. For quick validation, use $annotations['MyAnnotation'] to check existence/value. When iterating over many classes/methods (e.g., in a framework bootstrap), switch to AnnotationFactory to avoid redundant parsing—cache by MD5 hash automatically. Start with simple boolean annotations (e.g., @Enabled) before advancing to values, lists, or maps.

use zpt\anno\Annotations;

$reflector = new ReflectionClass(MyService::class);
$annos = new Annotations($reflector);

if ($annos['Enabled']) {
    // Apply logic
}

Implementation Patterns

• Custom Attribute-like Metadata: Tag services/controllers with domain-specific annotations (e.g., @Cacheable(minutes=15), @RateLimit(retries=3, window=60)) and resolve at runtime via reflection scanning during application boot.
• DI Container Integration: Extend Laravel’s container binding logic to read annotations (e.g., @Singleton, @Scoped("request")) on classes to override default resolution behavior—avoid conflicts by not mixing with Doctrine-based DI.
• CLI Command Discovery: Scan command classes for @Command("name") or @Task annotations on methods to auto-register actions (similar to how Artisan commands work, but self-contained in classes).
• API Route Definitions: In lightweight routing setups, define @Route("/path", methods={"GET"}) on controller methods and build a router that inspects these annotations at startup, avoiding external config files.
• Validation Orchestration: Use method annotations like @Validate({"field" => "required|email"}) to drive custom validation middleware that reads and applies rules dynamically.

Gotchas and Tips

• Case Sensitivity Quirks: Annotation names are case-insensitive (@Cached, @cached, @CACHED all map to ['cached']), but parameter names in maps are case-sensitive (@Cache(ttl=10) vs @Cache(TTL=10) create distinct keys). Always use consistent casing for parameters.
• Type Casting Gotchas: The library auto-casts 'true'/'false' strings to booleans and numeric strings to int/float, but quoted values (e.g., "123") may retain quotes or behave unexpectedly. Avoid quotes unless necessary.
• Nesting Limits: Only one level of nesting is supported in lists/maps (e.g., [ [a, b] ] works, but [[[a]]] doesn’t). For deeper structures, use JSON syntax (@Data {"a":{"b":[1]}})—but note the result will be a stdClass, not an array.
• Mixed-Type Lists Are Risky: Using the same annotation name multiple times (e.g., @Tag a, @Tag [b, c]) merges values, but mixing scalars and arrays may cause type confusion or unexpected outputs.
• Factory Caching Caveat: AnnotationFactory caches by MD5 of the entire doc comment string, so minor whitespace changes (e.g., newlines, indentation) can cause cache misses. Normalize annotations before relying on caching.
• No Laravel Integration: This doesn’t replace laravel/laravel-annotations or Doctrine-based tools—don’t expect compatibility with Route::get(), Eloquent casts, or validation rules. It’s best for custom, internal use cases where you control the reflection pipeline.