Alphalemon Bootstrap Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require alphalemon/alphalemon-bootstrap-bundle
   

   Add the bundle to AppKernel.php:

   public function registerBundles()
   {
       return [
           new AlphaLemon\BootstrapBundle\AlphaLemonBootstrapBundle(),
           // ... other bundles
       ];
   }
   

2. First Use Case:

   • Create an autoloader.json in your bundle’s root (e.g., src/Acme/MyBundle/autoloader.json):

     {
         "bundles": {
             "Acme\\MyBundle\\AcmeMyBundle": {}
         }
     }
     

   • The bundle will auto-register when the app boots (no manual AppKernel edits needed for basic cases).

3. Verify:

   • Run php app/console debug:container to confirm the bundle is loaded.

Implementation Patterns

1. Bundle Autoloading Workflow

• For Developers:
  • Define autoloader.json in your bundle’s root to declare dependencies and configurations.
  • Use environments to restrict bundles to specific environments (e.g., ["dev", "test"]).
  • Example:

    {
        "bundles": {
            "Vendor\\Bundle\\MyBundle": {
                "environments": ["dev", "test"],
                "overrides": ["Vendor\\BaseBundle"]
            }
        }
    }
    

• For Users:
  • Install via Composer; no manual AppKernel edits required for basic use.

2. Configuration Management

• Bundle-Specific Configs:
  • Place config.yml in Resources/config/ of your bundle. The bundle auto-copies it to app/config/bundles/[env]/.
  • Example: Define Assetic filters in your bundle’s config.yml to avoid user setup.
• Routing:
  • Add routing.yml to Resources/config/ for auto-loading routes.
  • Control priority with routing.priority in autoloader.json (e.g., 128 for higher priority).

3. Lifecycle Hooks

• Extend ActionManager to run scripts during:
  • packageInstalledPreBoot: Pre-init actions (e.g., DB migrations).
  • packageInstalledPostBoot: Post-init actions (e.g., container-aware tasks).
• Declare in autoloader.json:

  {
      "actionManager": "Vendor\\Bundle\\ActionManager\\MyActions"
  }
  

4. Integration with AppKernel

• Modify registerBundles() to use BundlesAutoloader:

  $bootstrapper = new \AlphaLemon\BootstrapBundle\Core\Autoloader\BundlesAutoloader(
      __DIR__,
      $this->getEnvironment(),
      $bundles
  );
  $bundles = $bootstrapper->getBundles();
  

• Update registerContainerConfiguration() to load auto-generated configs:

  $finder = new \Symfony\Component\Finder\Finder();
  $configFiles = $finder->depth(0)->name('*.yml')->in(__DIR__.'/config/bundles/config/'.$this->getEnvironment());
  foreach ($configFiles as $config) {
      $loader->load((string)$config);
  }
  

5. Routing Autoloader

• Enable in app/config/routing.yml:

  AlphaLemonBootstrapBundle:
      resource: .
      type: bootstrap
  

Gotchas and Tips

Pitfalls

1. Order Dependency Issues:

   • If overrides is misconfigured, bundles may load out of order, causing ClassNotFound errors.
   • Fix: Explicitly list dependencies in autoloader.json with correct overrides order.

2. Environment Mismatches:

   • Bundles marked for ["dev"] won’t load in prod. Test environments explicitly.
   • Fix: Use "all" or list all target environments.

3. Config Overwrites:

   • Auto-generated configs (app/config/bundles/[env]/) may conflict with manual configs.
   • Fix: Prefix bundle configs with the bundle name (e.g., acme_my_bundle: assetic: ...).

4. Routing Conflicts:

   • High-priority routes (priority > 0) may override lower-priority ones silently.
   • Fix: Test routes with php app/console debug:router and adjust priorities.

5. ActionManager Timing:

   • PreBoot actions run before the kernel initializes (no container access).
   • PostBoot actions receive the container but run after bootstrapping.
   • Fix: Use PostBoot for container-dependent tasks (e.g., service calls).

Debugging Tips

• Check Loaded Bundles:

  php app/console debug:container | grep "Bundle"
  

• Verify Configs:

  php app/console debug:config dump
  

• Inspect Autoloader: Enable debug mode to see BundlesAutoloader logs (add to app/AppKernel.php):

  $bootstrapper->setDebug(true);
  

Extension Points

1. Custom Autoloader Logic:

   • Extend BundlesAutoloader to add validation or dynamic bundle resolution.
   • Example: Skip bundles based on feature flags.

2. Dynamic Configs:

   • Use PostBoot actions to generate configs dynamically (e.g., fetch settings from an API).

3. Multi-Environment Setups:

   • Override getEnvironment() in AppKernel to support custom environment logic.

Performance Notes

• Avoid Overhead: Only use actionManager for critical tasks (e.g., DB setup). Prefer declarative configs.
• Cache Warmup: Auto-generated configs are cached; clear cache after bundle updates:

  php app/console cache:clear
  

Migration Tips

• From Manual Kernel Edits:
  • Replace new Vendor\Bundle() in AppKernel with autoloader.json entries.
  • Use overrides to maintain bundle order.
• From Symfony Flex:
  • This bundle predates Flex; use it for legacy projects or custom bundle setups.

```markdown
### **Pro Tip: Bundle Development Checklist**
1. Add `autoloader.json` to your bundle’s root.
2. Place `config.yml`/`routing.yml` in `Resources/config/` for auto-configuration.
3. Implement `ActionManager` for post-install tasks (if needed).
4. Test in all target environments (`dev`, `prod`, etc.).
5. Document `autoloader.json` requirements in your bundle’s README.