Metadata Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require splash/metadata
   

   Publish the configuration (if needed):

   php artisan vendor:publish --provider="Splash\Metadata\MetadataServiceProvider"
   

2. Basic Usage Register the service provider in config/app.php:

   'providers' => [
       // ...
       Splash\Metadata\MetadataServiceProvider::class,
   ],
   

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

   use Splash\Metadata\Metadata;
   
   class ExampleController extends Controller
   {
       protected $metadata;
   
       public function __construct(Metadata $metadata)
       {
           $this->metadata = $metadata;
       }
   
       public function show()
       {
           $metadata = $this->metadata->get('some.key');
           return response()->json($metadata);
       }
   }
   

4. Configuration Check config/metadata.php for default settings (e.g., storage paths, caching).

Implementation Patterns

Core Workflows

1. Fetching Metadata Retrieve metadata by key (supports dot notation for nested structures):

   $value = $this->metadata->get('user.profile.name');
   

2. Caching Metadata Enable caching via config:

   'cache' => [
       'enabled' => true,
       'driver' => 'file', // or 'redis', 'array'
   ],
   

   Clear cache manually:

   php artisan metadata:clear-cache
   

3. Dynamic Metadata Sources Extend with custom sources (e.g., database, API):

   $this->metadata->addSource(new DatabaseMetadataSource());
   

4. Middleware Integration Attach metadata to requests/responses:

   $this->metadata->set('request.id', $request->id);
   

Integration Tips

• Symfony Compatibility: Works seamlessly with Symfony components (e.g., HttpFoundation).
• Laravel-Specific: Use app('metadata') for container access.
• Event Listeners: Trigger actions on metadata changes:

  $this->metadata->onChange('user.status', function ($newValue) {
      Log::info("Status changed to: {$newValue}");
  });
  

Gotchas and Tips

Common Pitfalls

1. Key Collisions Avoid overwriting built-in keys (e.g., app.*). Use namespaced keys:

   $this->metadata->set('app.custom.key', $value);
   

2. Caching Quirks

   • Cache drivers must be configured in Laravel’s config/cache.php.
   • Clear cache after manual updates:

     php artisan metadata:clear-cache
     

3. Thread Safety Avoid concurrent writes to shared metadata keys. Use locks if needed:

   $this->metadata->lock('critical.key', function () {
       // Thread-safe operations
   });
   

Debugging Tips

• Log Metadata Enable debug mode in config:

  'debug' => true,
  

  Logs will appear in storage/logs/metadata.log.

• Validate Sources Ensure custom sources implement Splash\Metadata\SourceInterface:

  class CustomSource implements SourceInterface {
      public function get($key) { ... }
      public function set($key, $value) { ... }
  }
  

Extension Points

1. Custom Drivers Extend Splash\Metadata\Driver\AbstractDriver for new storage backends.

2. Middleware Create middleware to inject metadata from headers/cookies:

   $this->metadata->set('request.ip', $request->ip());
   

3. Validation Add validation rules to metadata keys:

   $this->metadata->validate('user.age', function ($value) {
       return is_int($value) && $value >= 0;
   });