Hwa Meta Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require hwavina/hwa-meta
   

   The package auto-registers its service provider, so no manual registration is required unless overriding defaults.

2. First Use Case: Access metadata utilities via the facade:

   use Hwavina\HwaMeta\Facades\HwaMeta;
   
   // Example: Generate a unique ID
   $id = Hwavina\HwaMeta\Facades\HwaMeta::generateId();
   

3. Where to Look First:

   • Facade: Hwavina\HwaMeta\Facades\HwaMeta (primary entry point).
   • Config: config/hwa_meta.php (customize behavior like ID formats, metadata defaults).
   • Documentation: Check the GitHub README for built-in functions (e.g., generateId(), getMetadata(), sanitize()).

Implementation Patterns

Core Workflows

1. Metadata Management:

   • Store/retrieve metadata for models, routes, or APIs:

     // Store metadata for a model
     HwaMeta::setMetadata('user:123', ['role' => 'admin', 'last_active' => now()]);
     
     // Retrieve metadata
     $data = HwaMeta::getMetadata('user:123');
     

2. ID Generation:

   • Generate unique IDs with customizable formats (e.g., UUID, timestamp-based):

     // Default UUID
     $uuid = HwaMeta::generateId();
     
     // Custom format (e.g., "USER-{timestamp}")
     HwaMeta::setIdFormat('USER-{timestamp}');
     $customId = HwaMeta::generateId();
     

3. Data Sanitization:

   • Clean user input or API responses:

     $cleaned = HwaMeta::sanitize($dirtyInput, 'html'); // Sanitize HTML
     

4. Integration with Laravel Components:

   • Models: Attach metadata to Eloquent models via accessors/mutators:

     class User extends Model {
         public function getMetadataAttribute() {
             return HwaMeta::getMetadata("user:{$this->id}");
         }
     }
     

   • Routes: Tag routes with metadata for middleware or logging:

     Route::get('/admin', function () {
         HwaMeta::setMetadata('route:admin', ['requires' => 'auth.admin']);
     })->middleware('checkRouteMeta');
     

5. Caching Metadata:

   • Leverage Laravel’s cache to store metadata temporarily:

     HwaMeta::setMetadata('temp:key', $data, 3600); // Cache for 1 hour
     

Advanced Patterns

• Dynamic Metadata Keys: Use dynamic keys for scalable metadata (e.g., user:{id}:preferences).
• Middleware for Metadata: Create middleware to inject metadata into requests/responses:

  public function handle($request, Closure $next) {
      HwaMeta::setMetadata('request:'.$request->id, ['ip' => $request->ip()]);
      return $next($request);
  }
  

Gotchas and Tips

Pitfalls

1. Namespace Collisions:

   • The package uses Hwavina\HwaMeta namespace. Ensure no conflicts with other packages (e.g., custom HwaMeta classes).
   • Fix: Use fully qualified namespaces or aliases.

2. Metadata Storage:

   • By default, metadata is stored in memory (not persisted). Use Laravel’s cache/database for persistence:

     HwaMeta::setStorage('database'); // Configure in config/hwa_meta.php
     

   • Warning: Memory storage resets on app restart.

3. ID Format Overrides:

   • Custom setIdFormat() affects all subsequent calls. Reset to default with:

     HwaMeta::setIdFormat(); // Reverts to UUID
     

4. Sanitization Limits:

   • The sanitize() method may not cover all edge cases (e.g., nested arrays). Extend the package:

     HwaMeta::extend('customSanitize', function ($input) {
         // Custom logic
         return $input;
     });
     

Debugging

• Check Config: Verify config/hwa_meta.php for misconfigurations (e.g., wrong storage driver).
• Log Metadata: Use Laravel’s logging to inspect metadata:

  \Log::info('Metadata:', HwaMeta::getMetadata('key'));
  

• Clear Cache: If metadata behaves unexpectedly, clear Laravel’s cache:

  php artisan cache:clear
  

Extension Points

1. Custom Storage: Extend the storage system by implementing Hwavina\HwaMeta\Contracts\StorageInterface:

   class DatabaseStorage implements StorageInterface {
       public function get($key) { /* ... */ }
       public function set($key, $value, $ttl = null) { /* ... */ }
   }
   

   Register it in config/hwa_meta.php:

   'storage' => \App\Storage\DatabaseStorage::class,
   

2. Add Helper Functions: Extend the facade with custom methods:

   HwaMeta::extend('hashMetadata', function ($key) {
       return hash('sha256', HwaMeta::getMetadata($key));
   });
   

3. Event Listeners: Trigger events for metadata changes (e.g., metadata.stored):

   HwaMeta::listen('metadata.stored', function ($key, $value) {
       \Log::info("Metadata stored for $key");
   });
   

Performance Tips

• Batch Operations: Use HwaMeta::batch() to reduce I/O for bulk metadata operations:

  HwaMeta::batch(function ($meta) {
      $meta->set('user:1', ['role' => 'admin']);
      $meta->set('user:2', ['role' => 'guest']);
  });
  

• Avoid Over-Sanitization: Sanitize only when necessary to reduce CPU overhead.

Config Quirks

• Default TTL: The default time-to-live (TTL) for cached metadata is null (no expiration). Set explicitly:

  HwaMeta::setMetadata('key', $value, 3600); // 1-hour TTL
  

• Storage Drivers: Supported drivers: memory (default), cache, database. Configure in config/hwa_meta.php:

  'driver' => env('HWA_META_DRIVER', 'memory'),