Xxllnc To Ktb Bundle Laravel Package

Getting Started

Minimal Steps

1. Understand the Purpose: This bundle is a template for creating Symfony Flex bundles as plugins for the Common Gateway ecosystem. It’s not a standalone utility but a scaffold for extending Gateway functionality.

2. Prerequisites:

   • A running Common Gateway instance (Symfony-based).
   • Composer installed (or Docker with PHP/Composer).
   • Basic familiarity with Symfony bundles and Flex recipes.

3. First Use Case:

   • Clone this repo as a starting point for your custom plugin.
   • Replace XxllncToKtbBundle with your bundle name (e.g., MyCustomGatewayBundle).
   • Update metadata (e.g., composer.json, README.md, and bundle class annotations).

4. Installation:

   • Require the template bundle (temporarily) to bootstrap your project:

     composer require common-gateway/xxllnc-to-ktb-bundle:dev-main
     

   • Run the installation command to register the bundle’s schemas/dependencies:

     php bin/console commongateway:install common-gateway/xxllnc-to-ktb-bundle
     

   • Remove the template after setup (it’s only for scaffolding).

5. Where to Look First:

   • src/DependencyInjection/ → Bundle configuration and extensions.
   • Resources/config/ → YAML/XML services and routes.
   • README.md → Example workflows for plugin development.
   • composer.json → Flex recipe and dependencies.

Implementation Patterns

Core Workflows

1. Plugin Development Workflow

• Scaffold: Use this bundle as a template. Replace all XxllncToKtb references with your bundle’s namespace (e.g., MyCompany\MyPluginBundle).
• Structure:

  src/
  ├── DependencyInjection/          # Configuration, extensions
  │   ├── MyPluginExtension.php     # Override `load()` to add services/routes
  │   └── MyPluginExtension.php.dist
  ├── Resources/config/             # Services, routes, doctrine mappings
  │   ├── services.yaml
  │   └── routes.yaml
  └── MyPluginBundle.php            # Bundle class (annotate with `@Bundle`)
  

• Key Files:
  • MyPluginBundle.php: Annotate with @Bundle and define dependencies (e.g., CommonGatewayCoreBundle).
  • MyPluginExtension.php: Extend Symfony’s ExtensionInterface to load services/routes dynamically.
  • services.yaml: Define services (e.g., command buses, repositories) with tags like commongateway.command_handler.

2. Integration with Common Gateway

• Admin UI Discovery: The bundle is designed to be auto-discovered by Common Gateway’s Plugins tab. Ensure:
  • Your bundle’s composer.json includes a flex recipe (copy from this template).
  • The bundle implements CommonGateway\Plugin\PluginInterface (if extending functionality).
• Dependency Injection:
  • Use autoconfigure: true in services.yaml for auto-wiring.
  • Tag services for Common Gateway’s DI container (e.g., @tag {name: commongateway.command_handler}).
• Commands/Console:
  • Place custom commands in src/Command/ and tag them with console.command.
  • Example:

    # services.yaml
    services:
        MyPlugin\Command\MyCommand:
            tags: ['console.command']
            arguments: ['@my_plugin.service']
    

3. Database/Schema Extensions

• Use Doctrine migrations or YAML mappings in Resources/config/doctrine/ to extend Common Gateway’s database schema.
• Example:

  # Resources/config/doctrine/MyEntity.orm.yml
  MyPlugin\Entity\MyEntity:
      type: entity
      table: my_plugin_entity
      fields:
          id: ~
          name: { type: string }
  

• Run migrations via:

  php bin/console doctrine:migrations:diff
  php bin/console doctrine:migrations:migrate
  

4. Event Listeners/Subscribers

• Extend Common Gateway events by creating listeners in src/EventListener/ and tagging them:

  services:
      MyPlugin\EventListener\MyListener:
          tags:
              - { name: kernel.event_listener, event: commongateway.my_event, method: onMyEvent }
  

5. Flex Recipe for Distribution

• Customize the composer.json extra.flex section to define your plugin’s requirements:

  "extra": {
      "flex": {
          "common-gateway/bundle": {
              "type": "symfony-bundle",
              "replaces": {
                  "common-gateway/core": "*"
              }
          }
      }
  }
  

• Test locally by requiring your bundle:

  composer require my-vendor/my-plugin-bundle:dev-main
  

Integration Tips

1. Debugging Bundle Loading:

   • Use php bin/console debug:container MyPluginBundle to verify services are loaded.
   • Check var/log/dev.log for DI errors.

2. Testing Plugins:

   • Use Common Gateway’s built-in plugin tester or create a separate Symfony kernel for isolation:

     // tests/PluginTest.php
     $kernel = new Kernel('test', false);
     $kernel->boot();
     $container = $kernel->getContainer();
     

3. Versioning:

   • Follow SemVer for your plugin’s composer.json version.
   • Use dev-main for active development, 1.0.0 for stable releases.

4. Documentation:

   • Include a README.md with:
     • Installation steps (Composer + console command).
     • Configuration options (e.g., config/packages/my_plugin.yaml).
     • Example usage (e.g., "To use the my:command, run php bin/console my:command").

Gotchas and Tips

Pitfalls

1. Bundle Auto-Discovery:

   • Issue: Plugin doesn’t appear in the Common Gateway Plugins tab.
   • Fix:
     • Ensure the bundle’s composer.json has a type: symfony-bundle.
     • Verify the bundle is listed in config/bundles.php (Symfony 5.1+).
     • Check for typos in the bundle class namespace (e.g., MyPluginBundle vs. My_Plugin_Bundle).

2. Circular Dependencies:

   • Issue: MyPluginExtension fails to load due to missing dependencies.
   • Fix:
     • Explicitly require CommonGatewayCoreBundle in composer.json:

       "require": {
           "common-gateway/core": "^1.0"
       }
       

     • Use parent::load() in MyPluginExtension to inherit core configurations.

3. Schema Conflicts:

   • Issue: Doctrine migrations fail due to duplicate column names.
   • Fix:
     • Prefix custom tables/columns (e.g., my_plugin_*).
     • Use doctrine:migrations:dump-schema to inspect the schema before applying.

4. Console Command Not Found:

   • Issue: php bin/console my:command returns "command not found".
   • Fix:
     • Ensure the command class is in src/Command/ and tagged in services.yaml.
     • Clear the cache:

       php bin/console cache:clear
       

5. Flex Recipe Not Triggering:

   • Issue: Running composer require doesn’t install the plugin via Flex.
   • Fix:
     • Verify the extra.flex section in composer.json is correctly formatted.
     • Test with a minimal recipe first (copy from this template).

Debugging Tips

1. Enable Debug Mode:

   APP_ENV=dev APP_DEBUG=1 php bin/console debug:container
   

   • Look for your bundle’s services under MyPluginBundle.

2. Log Configuration:

   • Add temporary logging in MyPluginExtension::load():

     $container->get('logger')->info('MyPluginExtension loaded', ['config' => $configs]);
     

3. Check Event Dispatcher:

   • Verify events are fired by adding a listener:

     // src/EventListener/DebugListener.php
     public function onKernelRequest(GetResponseEvent $event) {
         error_log('MyPlugin: Kernel request received');
     }
     

Extension Points

1. Custom Plugin Interface:
   • Implement CommonGateway\Plugin\PluginInterface to add metadata (e.g., name, version, description) for the admin UI:

     class MyPluginBundle extends Bundle implements PluginInterface {
         public function getPluginMetadata(): array {
             return [
                 'name' => 'My Awesome Plugin',
                 'version' => '1.0.0',
                 'description' => 'Extends Gateway with XYZ features.',