Plugin Bundle Laravel Package

Getting Started

First Steps

1. Installation:

   • Require via Composer:

     composer require codeages/plugin-bundle
     

   • Publish assets (if needed):

     php artisan vendor:publish --provider="Codeages\PluginBundle\PluginBundleServiceProvider"
     

2. Create a Plugin Skeleton:

   • Follow the plugins/DemoPlugin/ structure from the README.
   • Initialize plugin.json with metadata (e.g., code, name, version).
   • Extend PluginBase in DemoPlugin.php.

3. First Use Case:

   • Register the plugin via CLI:

     php artisan plugin:register Demo
     

   • Verify registration by checking plugins table in the database or running:

     php artisan plugin:list
     

Implementation Patterns

Core Workflows

1. Plugin Lifecycle Management:

   • Registration: Use plugin:register to enable a plugin. Triggers onInstall() in PluginBase.
   • Uninstallation: Use plugin:remove to disable. Triggers onUninstall().
   • Activation/Deactivation: Use plugin:enable/plugin:disable for runtime toggling (hooks onEnable()/onDisable()).

2. Service Integration:

   • Dependency Injection: Bind services in DemoPlugin.php:

     protected function register()
     {
         $this->app->bind('DemoService', function ($app) {
             return new \DemoPlugin\Service\DemoService();
         });
     }
     

   • Route Binding: Define routes in DemoPlugin.php:

     protected function boot()
     {
         Route::prefix('demo')->group(function () {
             Route::get('/', 'Controller@index');
         });
     }
     

3. Database Migrations:

   • Place migrations in Migrations/ and run:

     php artisan plugin:migrate Demo
     

   • Rollback with:

     php artisan plugin:migrate:rollback Demo
     

4. Asset Management:

   • Use Resources/ for views, JS, or CSS.
   • Load assets in DemoPlugin.php:

     View::addNamespace('demo', __DIR__.'/Resources/views');
     

5. Event Handling:

   • Listen to Laravel events or plugin-specific events (e.g., PluginRegistered):

     $this->app->booting(function () {
         event(new \Codeages\PluginBundle\Events\PluginRegistered($this));
     });
     

Gotchas and Tips

Common Pitfalls

1. Namespace Collisions:

   • Ensure plugin classes use unique namespaces (e.g., \DemoPlugin\Service\DemoService).
   • Avoid overlapping with core Laravel or other plugins.

2. Migration Conflicts:

   • Tip: Use Schema::table() for altering existing tables to avoid conflicts.
   • Gotcha: Running plugin:migrate twice may fail if migrations aren’t idempotent. Use --force cautiously:

     php artisan plugin:migrate Demo --force
     

3. Service Provider Order:

   • Plugins load in alphabetical order by plugin.json "code". Prepend codes (e.g., A_Demo) to enforce priority.

4. Caching Issues:

   • Clear config/cache after plugin updates:

     php artisan config:clear
     php artisan cache:clear
     

5. Debugging:

   • Check plugin status with:

     php artisan plugin:status Demo
     

   • Log errors in onInstall()/onEnable() to diagnose failures.

Extension Points

1. Custom Commands:

   • Extend the plugin CLI with:

     $this->commands([
         \DemoPlugin\Console\CustomCommand::class,
     ]);
     

   • Register commands in DemoPlugin.php.

2. Plugin Hooks:

   • Override lifecycle methods in PluginBase:

     public function onInstall()
     {
         // Custom logic (e.g., seed data)
     }
     

3. Dynamic Configuration:

   • Use config() in PluginBase to merge settings:

     $this->mergeConfigFrom(__DIR__.'/Config/demo.php', 'demo');
     

4. Multi-Tenancy:

   • Store tenant-specific data in a plugins_demo table with a tenant_id column.
   • Use middleware to scope queries:

     $this->app->bind('tenant', function () {
         return Tenant::findOrFail(request()->tenant_id);
     });
     

5. Testing:

   • Mock plugins in tests by overriding the PluginManager:

     $pluginManager = \Mockery::mock(\Codeages\PluginBundle\PluginManager::class);
     $pluginManager->shouldReceive('getPlugin')->andReturn($mockPlugin);
     $this->app->instance(\Codeages\PluginBundle\PluginManager::class, $pluginManager);