Metadata Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require antwebes/metadata-bundle
   

   Register the bundle in config/bundles.php:

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

2. Basic Configuration Publish the default config:

   php artisan vendor:publish --tag=metadata-config
   

   Edit config/metadata.php to define your metadata sources (e.g., database, API, or static data).

3. First Use Case: Fetching Metadata Inject the MetadataService into a controller or service:

   use Antwebes\MetadataBundle\Service\MetadataService;
   
   public function __construct(private MetadataService $metadataService) {}
   
   public function showPageContent()
   {
       $metadata = $this->metadataService->get('page_title');
       return view('page', ['title' => $metadata]);
   }
   

Implementation Patterns

Core Workflows

1. Defining Metadata Sources Configure sources in config/metadata.php:

   'sources' => [
       'database' => [
           'driver' => 'database',
           'query' => 'SELECT title FROM pages WHERE id = :id',
           'params' => ['id' => 1],
       ],
       'api' => [
           'driver' => 'http',
           'url' => 'https://api.example.com/metadata',
           'method' => 'GET',
       ],
       'static' => [
           'driver' => 'static',
           'data' => ['description' => 'Default page description'],
       ],
   ],
   

2. Fetching Metadata Use the MetadataService to retrieve data:

   // Single key
   $title = $this->metadataService->get('page_title');
   
   // Multiple keys (returns associative array)
   $data = $this->metadataService->get(['title', 'description']);
   
   // Fallback to default if key not found
   $author = $this->metadataService->get('author', 'Unknown Author');
   

3. Dynamic Metadata (e.g., Route-Based) Bind metadata to routes in routes/web.php:

   Route::get('/blog/{slug}', function ($slug) {
       $metadata = app('metadata')->get(['title', 'excerpt'], ['slug' => $slug]);
       return view('blog.post', $metadata);
   })->name('blog.post');
   

4. Caching Strategies Enable caching in config:

   'cache' => [
       'enabled' => true,
       'ttl' => 3600, // 1 hour
   ],
   

   Clear cache manually:

   php artisan metadata:clear-cache
   

5. Integration with Blade Share metadata globally in AppServiceProvider:

   public function boot()
   {
       View::share('metadata', $this->metadataService->getAll());
   }
   

   Use in Blade:

   <title>{{ $metadata['page_title'] ?? 'Default Title' }}</title>
   

Gotchas and Tips

Common Pitfalls

1. Driver Configuration Errors

   • Ensure driver keys in config/metadata.php match registered drivers (e.g., database, http, static).
   • Fix: Verify drivers exist in src/Service/Drivers/ or extend the bundle (see below).

2. Caching Issues

   • Cache may stale if underlying data changes (e.g., database records).
   • Fix: Use shorter TTLs for dynamic data or implement cache invalidation logic.

3. Missing Dependencies

   • The database driver requires doctrine/dbal or illuminate/database.
   • Fix: Install dependencies explicitly:

     composer require doctrine/dbal
     

4. Static Data Overrides

   • Static data in config takes precedence over other sources if keys collide.
   • Tip: Use unique keys or disable static sources if not needed.

5. HTTP Driver Timeouts

   • API calls may hang if no timeout is set.
   • Fix: Configure in config/metadata.php:

     'http' => [
         'timeout' => 5, // seconds
     ],
     

Debugging Tips

• Log Metadata Sources: Enable debug mode in config:

  'debug' => true,
  

  Check logs for resolved metadata (e.g., storage/logs/laravel.log).

• Validate Config: Use the metadata:validate artisan command:

  php artisan metadata:validate
  

• Override Drivers: Extend the bundle by creating custom drivers in app/Service/Drivers/. Example:

  namespace App\Service\Drivers;
  
  use Antwebes\MetadataBundle\Service\DriverInterface;
  
  class CustomDriver implements DriverInterface
  {
      public function fetch($key, array $params = [])
      {
          return "Custom data for {$key}";
      }
  }
  

  Register in config/metadata.php:

  'drivers' => [
      'custom' => App\Service\Drivers\CustomDriver::class,
  ],
  

Extension Points

1. Custom Drivers: Implement DriverInterface for new data sources (e.g., Redis, Elasticsearch).

2. Middleware for Metadata: Create middleware to inject metadata into requests:

   namespace App\Http\Middleware;
   
   use Antwebes\MetadataBundle\Service\MetadataService;
   
   class InjectMetadata
   {
       public function __construct(private MetadataService $metadata) {}
   
       public function handle($request, Closure $next)
       {
           $request->merge($this->metadata->getAll());
           return $next($request);
       }
   }
   

3. Event Listeners: Listen for metadata events (e.g., Metadata.Fetched) to log or transform data:

   use Antwebes\MetadataBundle\Events\MetadataFetched;
   
   MetadataFetched::listen(function (MetadataFetched $event) {
       \Log::debug('Metadata fetched:', $event->data);
   });
   

4. Testing: Mock the MetadataService in tests:

   $this->mock(MetadataService::class)
        ->shouldReceive('get')
        ->with('page_title')
        ->andReturn('Test Title');