Metadata Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require chamber-orchestra/metadata-bundle
   

   Add to config/bundles.php in Symfony:

   return [
       // ...
       ChamberOrchestra\MetadataBundle\MetadataBundle::class => ['all' => true],
   ];
   

2. First Use Case: Annotate an Entity

   use ChamberOrchestra\MetadataBundle\Annotation\Metadata;
   
   #[ORM\Entity]
   #[Metadata('cacheable' => true, 'driver' => 'doctrine')]
   class Product
   {
       // ...
   }
   

3. Access Metadata via Reader

   $reader = $container->get('metadata.reader');
   $metadata = $reader->loadMetadata(Product::class);
   // Returns array: ['cacheable' => true, 'driver' => 'doctrine']
   

Implementation Patterns

Core Workflows

1. Attribute-Driven Metadata

   • Use #[Metadata] on entities/classes to define cacheable, driver-specific, or embedded metadata.
   • Example: Embedded entity with custom driver:

     #[Metadata('embedded' => true, 'driver' => 'custom')]
     class Address {}
     

2. Cacheable Mapping

   • Enable caching via #[Metadata('cacheable' => true)] to optimize repeated metadata reads.
   • Configure cache driver in config/packages/metadata.yaml:

     chamber_orchestra_metadata:
         cache_driver: apcu
     

3. Event-Driven Extensions

   • Subscribe to MetadataEvents (e.g., MetadataLoadedEvent) to modify metadata dynamically:

     use ChamberOrchestra\MetadataBundle\Event\MetadataLoadedEvent;
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
     
     class CustomMetadataSubscriber implements EventSubscriberInterface
     {
         public static function getSubscribedEvents(): array
         {
             return [
                 MetadataLoadedEvent::class => 'onMetadataLoaded',
             ];
         }
     
         public function onMetadataLoaded(MetadataLoadedEvent $event): void
         {
             $metadata = $event->getMetadata();
             $metadata['custom_field'] = 'value'; // Extend metadata
         }
     }
     

4. Driver Integration

   • Register custom drivers in services.yaml:

     services:
         ChamberOrchestra\MetadataBundle\Driver\DriverInterface $custom_driver:
             class: App\Driver\CustomDriver
             tags: ['metadata.driver']
     

Gotchas and Tips

Pitfalls

1. Cache Invalidation

   • Clear cache after schema updates:

     php bin/console cache:clear
     

   • Use #[Metadata('cacheable' => false)] for volatile metadata.

2. Driver Priority

   • Drivers are resolved in registration order. Explicitly tag with priority in services.yaml:

     tags: ['metadata.driver', { name: 'metadata.driver', priority: 100 }]
     

3. Annotation vs. Attribute

   • The bundle supports both #[Metadata] (PHP 8+) and @Metadata (legacy). Prefer attributes for new projects.

4. Circular Dependencies

   • Avoid recursive metadata definitions (e.g., Product referencing Address which references Product).

Debugging

• Enable Debug Mode Set APP_DEBUG=true in .env to log metadata events:

  // config/packages/dev/metadata.yaml
  chamber_orchestra_metadata:
      debug: true
  

• Inspect Loaded Metadata Use the debug command:

  php bin/console debug:metadata App\Entity\Product
  

Extension Points

1. Custom Metadata Keys Extend the MetadataReader to support additional keys:

   $reader->addSupportedKey('custom_key');
   

2. Metadata Validation Implement MetadataValidatorInterface to enforce rules:

   use ChamberOrchestra\MetadataBundle\Validator\MetadataValidatorInterface;
   
   class RequiredDriverValidator implements MetadataValidatorInterface
   {
       public function validate(array $metadata): void
       {
           if (!isset($metadata['driver'])) {
               throw new \InvalidArgumentException('Driver is required.');
           }
       }
   }
   

3. Embedded Entity Handling Use #[Metadata('embedded' => true)] for lightweight entities. Override the EmbeddedMetadataDriver for custom logic:

   services:
       ChamberOrchestra\MetadataBundle\Driver\EmbeddedMetadataDriver:
           class: App\Driver\CustomEmbeddedDriver