Kiss Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer in your Symfony/Laravel project (if using Laravel, wrap it in a Symfony microkernel or use a bridge like symfony/bridge):

   composer require common-gateway/kiss-bundle
   

2. Enable the Bundle Register the bundle in your config/bundles.php (Symfony) or equivalent Laravel service provider:

   // config/bundles.php
   return [
       CommonGateway\KissBundle\KissBundle::class => ['all' => true],
   ];
   

3. First Use Case: Plugin Structure Create a basic plugin structure under src/Kiss/Plugin/ (or your preferred namespace):

   src/
   ├── Kiss/
   │   ├── Plugin/
   │   │   ├── ExamplePlugin.php
   │   │   └── Resources/
   │   │       ├── config/
   │   │       └── public/
   

4. Define a Plugin Implement the PluginInterface in your plugin class:

   namespace Kiss\Plugin;
   
   use CommonGateway\KissBundle\Plugin\PluginInterface;
   
   class ExamplePlugin implements PluginInterface
   {
       public function getName(): string
       {
           return 'example_plugin';
       }
   
       public function getDescription(): string
       {
           return 'A demo plugin for KissBundle';
       }
   }
   

5. Register the Plugin Use the PluginManager to register your plugin in a service or controller:

   use CommonGateway\KissBundle\Plugin\PluginManager;
   
   class ExampleController
   {
       public function __construct(private PluginManager $pluginManager)
       {
       }
   
       public function index()
       {
           $plugins = $this->pluginManager->getPlugins();
           // Use $plugins...
       }
   }
   

Implementation Patterns

Plugin Discovery

• Automatic Discovery: Plugins are auto-discovered via Symfony’s autowiring if they implement PluginInterface and are in a Plugin/ namespace.
• Manual Registration: Use PluginManager::registerPlugin() for dynamic registration:

  $this->pluginManager->registerPlugin(new ExamplePlugin());
  

Configuration

• Flexible Config: Override default plugin behavior via config/packages/kiss.yaml:

  kiss:
      plugins:
          enabled: ['example_plugin', 'another_plugin']
          disabled: ['deprecated_plugin']
  

Event-Driven Workflows

• Plugin Events: Listen to kiss.plugin.registered or kiss.plugin.disabled events:

  use Symfony\Component\EventDispatcher\EventSubscriberInterface;
  use CommonGateway\KissBundle\Event\PluginEvent;
  
  class PluginSubscriber implements EventSubscriberInterface
  {
      public static function getSubscribedEvents(): array
      {
          return [
              PluginEvent::REGISTERED => 'onPluginRegistered',
          ];
      }
  
      public function onPluginRegistered(PluginEvent $event)
      {
          // Handle plugin registration logic
      }
  }
  

Asset Management

• Public Assets: Place static files in Plugin/Resources/public/ and use the AssetManager:

  $this->assetManager->addPluginAsset('example_plugin', 'css/style.css');
  

Dependency Injection

• Service Integration: Inject plugins as services or use the PluginManager to fetch them:

  // services.yaml
  services:
      Kiss\Plugin\ExamplePlugin:
          tags: ['kiss.plugin']
  

Gotchas and Tips

Pitfalls

1. Namespace Conflicts Ensure your plugin classes are in a unique namespace (e.g., App\Plugin\) to avoid collisions with other bundles.

2. Circular Dependencies Avoid circular dependencies between plugins. Use lazy-loading or dependency injection carefully.

3. Configuration Overrides Be cautious when overriding kiss.yaml—changes may affect all plugins globally. Use environment-specific configs (e.g., kiss_dev.yaml) for testing.

4. Asset Pipeline Issues If assets (CSS/JS) fail to load, verify:

   • Files are in Plugin/Resources/public/.
   • The AssetManager is properly configured in your bundle.

5. Plugin Lifecycle Plugins are initialized when the PluginManager is first called. Avoid heavy initialization logic in the constructor.

Debugging

• Enable Debug Mode Set KISS_DEBUG=true in your environment to log plugin events and errors:

  // .env
  KISS_DEBUG=1
  

• Check Registered Plugins Dump the active plugins to verify registration:

  dd($this->pluginManager->getPlugins());
  

Extension Points

1. Custom Plugin Interfaces Extend PluginInterface to add methods:

   interface CustomPluginInterface extends PluginInterface
   {
       public function customMethod();
   }
   

2. Plugin Middleware Use Symfony’s middleware system to intercept plugin calls:

   use CommonGateway\KissBundle\Event\PluginEvent;
   use Symfony\Component\HttpKernel\Event\RequestEvent;
   
   $event->getResponse()->headers->set('X-Plugin', $event->getPlugin()->getName());
   

3. Database Integration Store plugin-specific data in a shared database table with a plugin_name column for isolation.

4. Localization Use Symfony’s translation system with plugin-specific translation domains:

   # Plugin/Resources/translations/messages.en.yaml
   example_plugin:
       greeting: "Hello from %name%!"
   

5. Testing Mock the PluginManager in tests:

   $pluginManager = $this->createMock(PluginManager::class);
   $pluginManager->method('getPlugin')->willReturn(new ExamplePlugin());