App Registry Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require aeruz/app-registry
   

   Add the service provider to config/app.php:

   'providers' => [
       Aeruz\AppRegistry\Providers\AppRegistryServiceProvider::class,
   ],
   

2. Publish Config & Migrations

   php artisan vendor:publish --provider="Aeruz\AppRegistry\Providers\AppRegistryServiceProvider" --tag="config"
   php artisan vendor:publish --provider="Aeruz\AppRegistry\Providers\AppRegistryServiceProvider" --tag="migrations"
   

   Run migrations:

   php artisan migrate
   

3. First Use Case: Registering an App

   use Aeruz\AppRegistry\Contracts\AppRegistry;
   use Aeruz\AppRegistry\Models\App;
   
   $registry = app(AppRegistry::class);
   $app = $registry->create([
       'name' => 'My Awesome App',
       'description' => 'Does amazing things',
       'owner_id' => auth()->id(),
   ]);
   

Implementation Patterns

Core Workflows

1. Lifecycle Management

   // Draft → Published (with validation)
   $app->publish(); // Throws \Aeruz\AppRegistry\Exceptions\AppValidationException if invalid
   
   // Published → Draft (soft delete)
   $app->draft();
   

2. Locking Mechanism

   // Acquire lock for exclusive operations (e.g., config updates)
   $lock = $app->lock();
   try {
       // Critical section
       $app->updateConfig(['key' => 'value']);
   } finally {
       $lock->release();
   }
   

3. Access Control

   // Check if current user can manage the app
   if ($registry->canManage($app, auth()->user())) {
       // Proceed with operations
   }
   

Integration Tips

• Event Listeners: Bind to AppPublished, AppDrafted, or AppLocked events for notifications/analytics.

  Event::listen(AppPublished::class, function ($event) {
      Log::info("App published: {$event->app->name}");
  });
  

• API Resources: Use AppResource for consistent JSON responses.

  return new AppResource($app);
  

• Policy Integration: Extend AppPolicy for custom authorization logic.

Gotchas and Tips

Pitfalls

1. Locking Deadlocks

   • Always release locks in a finally block to avoid orphaned locks.
   • Use tryLock() for non-blocking attempts:

     $lock = $app->tryLock(5); // Timeout after 5 seconds
     

2. Validation Overrides

   • Customize validation by extending App model and overriding rules():

     protected function rules(): array
     {
         return array_merge(parent::rules(), [
             'custom_field' => 'required|unique:apps',
         ]);
     }
     

3. Migration Conflicts

   • If extending the apps table, run:

     php artisan app-registry:migrate-extend
     

Debugging

• Lock Debugging: Enable lock logging in config/app-registry.php:

  'debug' => [
      'locks' => env('APP_REGISTRY_DEBUG_LOCKS', false),
  ],
  

• Event Debugging: Use AppRegistry::debugEvents(true) to log all events.

Extension Points

1. Custom Fields Add via model events:

   App::created(function ($app) {
       $app->customFields()->create(['key' => 'theme', 'value' => 'dark']);
   });
   

2. Webhooks Implement Aeruz\AppRegistry\Contracts\WebhookHandler for external notifications:

   class SlackWebhook implements WebhookHandler
   {
       public function handle(AppEvent $event): void
       {
           // Send Slack notification
       }
   }
   

3. Rate Limiting Use middleware to throttle operations:

   Route::middleware(['throttle:10,1'])->group(function () {
       // Rate-limited routes
   });