Corebundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation

   composer require commongateway/corebundle
   

   Add the bundle to config/bundles.php in Symfony:

   return [
       // ...
       CommonGateway\CoreBundle\CommonGatewayCoreBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Create a config/packages/commongateway.yaml file:

   commongateway:
       plugins_dir: "%kernel.project_dir%/var/plugins"
       default_plugin: "base_plugin"
   

3. First Plugin Setup

   • Create a plugins/base_plugin/installation.json:

     {
         "name": "Base Plugin",
         "version": "1.0.0",
         "endpoints": [
             {
                 "path": "/api/data",
                 "methods": ["GET"],
                 "handler": "App\\Plugin\\DataHandler"
             }
         ]
     }
     

   • Implement a handler (e.g., src/Plugin/DataHandler.php):

     namespace App\Plugin;
     
     use CommonGateway\CoreBundle\Plugin\AbstractHandler;
     
     class DataHandler extends AbstractHandler
     {
         public function handleGet(): array
         {
             return ['data' => 'Hello, Common Gateway!'];
         }
     }
     

4. Register Plugin Run the installation service to register the plugin:

   php bin/console commongateway:install-plugin base_plugin
   

5. Test the Endpoint Access the endpoint via HTTP:

   curl http://localhost:8000/api/data
   

Where to Look First

• Documentation: Check src/Resources/doc/ for bundle-specific docs.
• Configuration: Review config/packages/commongateway.yaml for available options.
• Plugin Structure: Study var/plugins/ for example plugin layouts.
• Commands: Run php bin/console list commongateway to explore CLI tools.

Implementation Patterns

Plugin Development Workflow

1. Plugin Structure

   • installation.json: Defines metadata, endpoints, and dependencies.

     {
         "name": "MyPlugin",
         "version": "1.0.0",
         "endpoints": [
             {
                 "path": "/custom/endpoint",
                 "methods": ["POST"],
                 "handler": "App\\Plugin\\CustomHandler",
                 "middleware": ["auth", "validate"]
             }
         ],
         "dependencies": ["base_plugin"]
     }
     

   • Handler Classes: Extend AbstractHandler and implement methods for HTTP verbs (handleGet, handlePost, etc.).

     class CustomHandler extends AbstractHandler
     {
         public function handlePost(array $data): array
         {
             // Process data, validate, and return response
             return $this->json(['status' => 'success']);
         }
     }
     

2. Middleware Integration Use middleware for cross-cutting concerns (e.g., auth, logging):

   # config/packages/commongateway.yaml
   commongateway:
       middleware:
           auth: App\Middleware\AuthMiddleware
           validate: App\Middleware\ValidationMiddleware
   

3. Dynamic Schema Generation Leverage the InstallationService to auto-generate database schemas from plugin definitions:

   php bin/console commongateway:generate-schema my_plugin
   

4. RBAC Integration Define roles and permissions in installation.json:

   {
       "roles": {
           "admin": ["create", "read", "update", "delete"],
           "user": ["read"]
       }
   }
   

   Use the AuthorizationChecker in handlers:

   if (!$this->authorizationChecker->isGranted('ROLE_ADMIN')) {
       throw new AccessDeniedException();
   }
   

Integration with Laravel

1. Symfony-Laravel Bridge Use symfony/bridge to integrate Symfony bundles with Laravel:

   composer require symfony/bridge
   

   Configure Laravel’s service provider to load the bundle:

   // config/app.php
   'providers' => [
       // ...
       Symfony\Component\HttpKernel\HttpKernelBundle\HttpKernelBundle::class,
       CommonGateway\CoreBundle\CommonGatewayCoreBundle::class,
   ],
   

2. Routing Extend Laravel’s router to include Common Gateway endpoints:

   // routes/web.php
   Route::get('/api/data', function () {
       return app(\CommonGateway\CoreBundle\Gateway::class)->handleRequest();
   });
   

3. Service Container Bind Symfony services to Laravel’s container:

   $app->singleton(\CommonGateway\CoreBundle\InstallationService::class, function ($app) {
       return new \CommonGateway\CoreBundle\InstallationService(
           $app->make('config'),
           $app->make('filesystem')
       );
   });
   

4. Event Listeners Subscribe to Common Gateway events (e.g., PluginInstalledEvent):

   // EventSubscriber
   class PluginEventSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               'commongateway.plugin.installed' => 'onPluginInstalled',
           ];
       }
   
       public function onPluginInstalled(PluginInstalledEvent $event)
       {
           // Log or trigger Laravel events
           event(new \App\Events\PluginInstalled($event->getPlugin()));
       }
   }
   

Gotchas and Tips

Pitfalls

1. Plugin Dependency Hell

   • Issue: Circular dependencies between plugins can break installation.
   • Fix: Use dependencies in installation.json and validate with:

     php bin/console commongateway:validate-plugins
     

2. Handler Naming Collisions

   • Issue: Duplicate handler class names across plugins.
   • Fix: Prefix handler classes with plugin names (e.g., MyPlugin\DataHandler).

3. Middleware Order Matters

   • Issue: Incorrect middleware execution order (e.g., auth before validation).
   • Fix: Define middleware order in installation.json:

     {
         "endpoints": [
             {
                 "middleware": ["validate", "auth"]
             }
         ]
     }
     

4. Caching Headaches

   • Issue: Stale plugin configurations after updates.
   • Fix: Clear the cache after plugin changes:

     php bin/console cache:clear
     php bin/console commongateway:clear-cache
     

5. RBAC Misconfigurations

   • Issue: Overly permissive or restrictive role definitions.
   • Fix: Test roles with:

     php bin/console commongateway:check-permissions admin /api/data
     

Debugging Tips

1. Enable Verbose Logging

   # config/packages/commongateway.yaml
   commongateway:
       debug: true
   

   Check logs at var/log/commongateway.log.

2. Dump Plugin Metadata

   php bin/console commongateway:debug-plugin base_plugin
   

3. Test Endpoints Locally Use Symfony’s built-in server for testing:

   php bin/console server:run
   

4. Validate JSON Schemas Ensure installation.json is valid JSON:

   php bin/console commongateway:validate-json plugins/base_plugin/installation.json
   

Extension Points

1. Custom Installation Logic Extend the InstallationService to add pre/post-install hooks:

   class CustomInstallationService extends \CommonGateway\CoreBundle\InstallationService
   {
       protected function postInstall(Plugin $plugin)
       {
           // Custom logic (e.g., send notification)
       }
   }
   

   Bind it in services:

   services:
       CommonGateway\CoreBundle\InstallationService:
           class: App\Service\CustomInstallationService
   

2. Dynamic Endpoint Routing Override the router to add dynamic routes:

   // src/CommonGateway/CoreBundle/DependencyInjection/Compiler/Pass.php
   public function process(ContainerBuilder $container)
   {
       $definition = $container->findDefinition('router');
       $definition->addMethodCall('addDynamicRoutes', [
           $container->getParameter('commongateway.endpoints')
       ]);
   }
   

3. Plugin Marketplace Build a marketplace for plugins by extending the PluginRepository:

   class MarketplacePluginRepository extends \CommonGateway\CoreBundle\Plugin\PluginRepository
   {
       public function fetchFromMarketplace(string $pluginName): Plugin
       {
           // Fetch and install from remote source
       }
   }
   

4. Webhook Support Add webhook endpoints by extending the Gateway class:

   class WebhookGateway extends \CommonGateway\CoreBundle\Gateway
   {
       public function handleWebhook(array $payload): array
       {
           // Process webhook payload
       }
   }