T Junction Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer (for development):

   composer require common-gateway/t-junction-bundle:dev-main
   

   Note: Use dev-main for active development; replace with a stable version tag in production.

2. Enable the Bundle in config/bundles.php:

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

3. First Use Case: Plugin Discovery

   • Navigate to the Common Gateway Admin UI → Plugins tab.
   • Search for and install the bundle (e.g., common-gateway/pet-store-bundle).
   • Verify installation via CLI:

     php bin/console commongateway:install common-gateway/pet-store-bundle
     

4. Verify Installation

   • Check the config/packages/commongateway.yaml for auto-generated plugin configurations.
   • Test routing by sending a message to the plugin’s endpoint (e.g., /api/pet-store).

Implementation Patterns

Core Workflows

1. Plugin Development

• Structure a Plugin Bundle:

  composer create-project common-gateway/t-junction-bundle my-plugin-bundle
  

  • Follow the TJunctionBundle skeleton for:
    • Resources/config/commongateway.yaml (plugin metadata).
    • DependencyInjection/Extension.php (schema/route registration).
    • Controller/ (API endpoints).

• Register Schemas/Routes: Extend CommonGateway\TJunctionBundle\DependencyInjection\Extension to define:

  # Resources/config/commongateway.yaml
  commongateway:
      plugins:
          my_plugin:
              schemas:
                  - "@MyPluginBundle/Resources/schemas/pet-store.json"
              routes:
                  - { path: "/pets", methods: ["GET"], controller: "MyPluginBundle:Pet:list" }
  

2. Plugin Installation & Activation

• Admin UI Flow:
  1. Upload the bundle via the Plugins tab.
  2. Activate the plugin (triggers commongateway:install under the hood).
• CLI Flow:

  # Install the plugin (downloads + configures)
  composer require common-gateway/my-plugin-bundle
  php bin/console commongateway:install common-gateway/my-plugin-bundle
  
  # Verify active plugins
  php bin/console debug:container | grep commongateway.plugin
  

3. Message Routing

• Inbound Messages: The bundle auto-discovers plugin routes and integrates them into Symfony’s router. Example: A message to /api/pet-store is routed to MyPluginBundle:PetStore:handle.

• Outbound Messages: Use the CommonGateway\Messenger\PluginMessageBus to dispatch messages to plugins:

  $bus->dispatch(new PetStoreMessage($data));
  

4. Configuration Management

• Dynamic Config: Plugin configs are merged into commongateway.yaml at runtime. Override defaults via:

  # config/packages/commongateway.yaml
  commongateway:
      plugins:
          my_plugin:
              settings:
                  timeout: 30
  

• Environment-Specific Configs: Use %kernel.environment% in commongateway.yaml:

  commongateway:
      plugins:
          my_plugin:
              debug: "%kernel.debug%"
  

Integration Tips

Symfony Messenger Integration

• Plugin as a Message Handler:

  // src/MessageHandler/PetStoreHandler.php
  use CommonGateway\Messenger\PluginMessageBus;
  
  class PetStoreHandler
  {
      public function __invoke(PetStoreMessage $message, PluginMessageBus $bus)
      {
          // Process message and reply via $bus->reply()
      }
  }
  

API Platform Integration

• Expose Plugin as API Resource:

  # config/api_platform/resources.yaml
  resources:
      MyPluginBundle\Entity\Pet:
          collectionOperations:
              get:
                  method: 'GET'
                  path: '/pets'
                  controller: 'MyPluginBundle:Pet:list'
  

Event Listeners

• Hook into Plugin Lifecycle:

  // src/EventListener/PluginInstaller.php
  use CommonGateway\TJunctionBundle\Event\PluginInstalledEvent;
  
  class PluginInstaller implements EventSubscriber
  {
      public static function getSubscribedEvents()
      {
          return [
              PluginInstalledEvent::class => 'onPluginInstalled',
          ];
      }
  
      public function onPluginInstalled(PluginInstalledEvent $event)
      {
          // Post-install logic (e.g., migrate data)
      }
  }
  

Gotchas and Tips

Pitfalls

1. Schema Validation Failures:

   • Issue: Plugins with invalid JSON schemas may fail silently during installation.
   • Fix: Validate schemas locally before uploading:

     php bin/console commongateway:validate-schemas common-gateway/my-plugin-bundle
     

2. Route Conflicts:

   • Issue: Plugin routes may clash with existing Symfony routes.
   • Fix: Use unique prefixes in commongateway.yaml:

     routes:
         - { path: "/my-plugin/pets", ... }
     

3. Circular Dependencies:

   • Issue: Plugins depending on other plugins may fail to install.
   • Fix: Use composer require with --ignore-platform-reqs if needed, or restructure dependencies.

4. Cache Invalidation:

   • Issue: Changes to commongateway.yaml require cache clearing:

     php bin/console cache:clear
     

5. Plugin Isolation:

   • Issue: Shared services between plugins may cause unintended side effects.
   • Fix: Scope services to the plugin namespace:

     $container->set('my_plugin.service', MyService::class, PluginScope::class);
     

Debugging Tips

1. Enable Debug Mode:

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

   • Logs plugin installation/activation steps to var/log/dev.log.

2. Inspect Active Plugins:

   php bin/console debug:container | grep commongateway.plugin.manager
   

3. Test Plugin Routes: Use Symfony’s built-in router debugger:

   php bin/console debug:router | grep my-plugin
   

4. Schema Debugging: Dump loaded schemas:

   php bin/console commongateway:debug-schemas
   

Extension Points

1. Custom Plugin Installer: Extend CommonGateway\TJunctionBundle\Installer\PluginInstaller to add pre/post-install hooks.

2. Dynamic Route Generation: Override CommonGateway\TJunctionBundle\Router\PluginRouter to modify route generation logic.

3. Plugin Metadata: Extend the PluginMetadata class to add custom metadata fields (e.g., version, author).

4. Messenger Transport: Add a custom transport for plugin-specific messaging:

   use CommonGateway\Messenger\Transport\PluginTransport;
   

5. Admin UI Customization: Override Twig templates in Resources/views/ to modify the Plugins tab UI.

Pro Tips

• Use dev-main for Development: Avoid stable tags until the plugin is production-ready.

• Automate Testing: Test plugin installation in CI with:

  php bin/console commongateway:install common-gateway/my-plugin-bundle --env=test
  

• Document Plugin Dependencies: Clearly list required plugins in composer.json:

  "extra": {
      "commongateway": {
          "requires": ["common-gateway/core-bundle"]
      }
  }
  

• Leverage Symfony Flex Recipes: Create a recipe for your plugin to simplify installation:

  composer create-recipe common-gateway/my-plugin-bundle