Distribution Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require akuma/distribution-bundle
   

2. Extend AkumaKernel Replace your AppKernel (or Kernel in Symfony 4+) with:

   // app/Kernel.php (Symfony 4+) or app/AppKernel.php (Symfony 3/2)
   class AppKernel extends AkumaKernel
   {
       public function registerBundles()
       {
           $bundles = parent::registerBundles(); // Load Akuma-registered bundles first
           $bundles[] = new Symfony\Bundle\FrameworkBundle\FrameworkBundle(); // Add your core bundles
           return $bundles;
       }
   }
   

3. Define a Bundle for Auto-Registration Create Resources/config/bundle.yml in your bundle (e.g., Acme/TestBundle):

   bundle:
       class: 'Acme\Bundle\TestBundle\AcmeTestBundle'
       priority: 10  # Higher = loaded later
       kernel: false # Set `true` if constructor requires Kernel
       environment: ['dev', 'prod']
       require: []    # Optional dependencies
   

4. Verify Registration Run the debug command:

   php bin/console akuma:debug:bundle
   

   Expected output: Your bundle listed under registered bundles.

First Use Case: Dynamic Bundle Loading

Use this to load optional or environment-specific bundles without modifying AppKernel directly. Example:

• Load a DebugBundle only in dev environment.
• Dynamically enable/disable bundles via config (e.g., feature flags).

Implementation Patterns

Workflow: Integrating with Existing Code

1. Bundle Registration

   • Place bundle.yml in every bundle you want auto-registered.
   • Use priority to control load order (e.g., -10 for core dependencies, 10 for optional features).
   • Set kernel: true if the bundle’s constructor requires Kernel (e.g., for container-aware services).

2. Dependency Management

   • Use require to declare bundle dependencies (Akuma will load them first).
   • Example:

     require:
         - { class: 'Acme\Bundle\AuthBundle\AuthBundle', kernel: true }
     

3. Environment-Specific Loading

   • Restrict bundles to environments via environment:

     environment: ['prod', 'staging']  # Skipped in 'dev'
     

4. Symfony 4+ Compatibility

   • For Symfony 4+, override getBundles() in Kernel.php:

     public function getBundles()
     {
         return array_merge(parent::getBundles(), [
             // Manually add non-Akuma bundles here
         ]);
     }
     

5. Debugging Registration

   • Use akuma:debug:bundle to inspect loaded bundles and their metadata.
   • Check for missing dependencies or environment mismatches.

Integration Tips

• Avoid Duplicates: Ensure bundle.yml class matches the actual bundle class name.
• Priority Conflicts: Lower priority values load first. Use negative numbers for core bundles.
• Circular Dependencies: Akuma does not validate require cycles. Test thoroughly.
• Symfony Flex: If using Symfony 4+, place bundle.yml in config/packages/your_bundle.yml (custom location).

Gotchas and Tips

Pitfalls

1. Kernel Constructor Issues

   • If kernel: true is set but the bundle’s constructor doesn’t accept Kernel, Akuma will fail silently. Always verify constructors.
   • Fix: Add use Symfony\Component\HttpKernel\KernelInterface; and update the constructor.

2. Environment Mismatches

   • Bundles with environment: ['prod'] won’t load in dev. Check with akuma:debug:bundle --env=prod.

3. Priority Overrides

   • Akuma merges bundles after the parent registerBundles(). If you override the entire method, you’ll lose Akuma’s auto-registration.
   • Fix: Use array_merge or + operator:

     return array_merge(parent::registerBundles(), [$yourBundle]);
     

4. Missing bundle.yml

   • Bundles without bundle.yml won’t be auto-registered. Verify file paths (case-sensitive on Linux).

5. Symfony 4+ Kernel Overrides

   • In Symfony 4+, AppKernel is replaced with Kernel. Ensure your Kernel extends AkumaKernel and overrides getBundles() correctly.

Debugging Tips

• Command Output: Run akuma:debug:bundle --env=prod --verbose to see raw bundle metadata.
• Log Errors: Enable debug mode (APP_DEBUG=1) to catch constructor failures.
• Manual Override: Temporarily disable Akuma by removing extends AkumaKernel to isolate issues.

Extension Points

1. Custom Bundle Loaders

   • Extend Akuma\Bundle\DistributionBundle\Loader\BundleLoader to add logic (e.g., load bundles from a database).

2. Dynamic Configuration

   • Override AkumaKernel::getBundleConfig() to fetch bundle.yml from a remote source (e.g., API).

3. Event Listeners

   • Listen to akuma.bundle.register (dispatches after bundle loading) to modify bundles post-registration:

     $eventDispatcher->addListener('akuma.bundle.register', function ($event) {
         $event->getBundles()[] = new YourDynamicBundle();
     });
     

4. Priority Adjustment

   • Dynamically set priority via config or environment variables:

     # config/packages/akuma.yml
     akuma:
         priority_adjustment: 5  # Adds 5 to all bundle priorities