Schema Api Updater Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require effectiveactivism/schema-api-updater
   

   Ensure your project uses Laravel 8+ (check composer.json for compatibility).

2. Publish Config

   php artisan vendor:publish --provider="EffectiveActivism\SchemaApiUpdater\SchemaApiUpdaterServiceProvider" --tag="config"
   

   Review config/schema-api-updater.php for API endpoints, authentication, and update strategies.

3. First Use Case: Fetching a Schema

   use EffectiveActivism\SchemaApiUpdater\Facades\SchemaUpdater;
   
   $schema = SchemaUpdater::fetch('https://example.com/schema.json');
   

   • Key Methods:
     • fetch($url): Retrieves a schema from a remote URL.
     • update($schema, $strategy = 'merge'): Updates a local schema with remote changes (supports merge, replace, or diff strategies).

Implementation Patterns

Workflow: Syncing Schemas

1. Define a Schema Model Extend EffectiveActivism\SchemaApiUpdater\Contracts\Schema or use Eloquent:

   use Illuminate\Database\Eloquent\Model;
   
   class AppSchema extends Model implements \EffectiveActivism\SchemaApiUpdater\Contracts\Schema {
       protected $fillable = ['name', 'content', 'updated_at'];
   }
   

2. Create an Updater Job Use Laravel Queues to avoid blocking requests:

   use EffectiveActivism\SchemaApiUpdater\Jobs\UpdateSchemaJob;
   
   UpdateSchemaJob::dispatch(
       schema: $appSchema,
       url: 'https://example.com/latest.json',
       strategy: 'merge'
   );
   

3. Event-Driven Updates Listen for schema changes via events:

   SchemaUpdater::on('schema.updated', function ($schema) {
       // Trigger downstream actions (e.g., cache invalidation)
   });
   

Integration Tips

• Caching: Cache fetched schemas to reduce API calls:

  SchemaUpdater::fetch($url, cacheMinutes: 60);
  

• Webhooks: Use the SchemaUpdated event to notify external services (e.g., via Laravel Horizon or a queue worker).
• Validation: Validate schemas before updating:

  SchemaUpdater::validate($schema, ['required' => ['properties.id']]);
  

Gotchas and Tips

Pitfalls

1. Authentication

   • If the Schema API requires auth, configure it in config/schema-api-updater.php:

     'auth' => [
         'token' => env('SCHEMA_API_TOKEN'),
         'header' => 'Authorization',
     ],
     

   • Gotcha: Hardcoded tokens in config may expose secrets. Use Laravel’s .env or a secrets manager.

2. Strategy Conflicts

   • The merge strategy prioritizes remote changes over local ones. Use replace cautiously:

     SchemaUpdater::update($localSchema, 'replace'); // Overwrites entirely!
     

3. Rate Limiting

   • Aggressive polling may hit API limits. Implement exponential backoff in your job:

     $this->handle()->retryAfter(10); // Retry after 10 seconds
     

Debugging

• Enable Logging Set 'debug' => true in config to log API responses and errors to storage/logs/laravel.log.
• Validate URLs Ensure URLs are absolute (e.g., https://example.com/schema.json, not /schema.json).

Extension Points

1. Custom Strategies Implement EffectiveActivism\SchemaApiUpdater\Contracts\UpdateStrategy:

   class CustomStrategy implements UpdateStrategy {
       public function apply($local, $remote) {
           // Custom logic (e.g., deep merge with conflict resolution)
       }
   }
   

   Register it in config/schema-api-updater.php:

   'strategies' => [
       'custom' => \App\Strategies\CustomStrategy::class,
   ],
   

2. Pre/Post Hooks Use the schema.updating and schema.updated events to inject logic:

   SchemaUpdater::on('schema.updating', function ($schema, $remote) {
       // Sanitize or transform $remote before update
   });