Rad Bundles Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require becklyn/rad-bundles
   

   No additional configuration is required—it’s a lightweight utility package.

2. First Use Case Check if a bundle is enabled in your Symfony/Laravel app (if using Symfony’s kernel):

   use Becklyn\RadBundles\BundleChecker;
   
   $isEnabled = BundleChecker::isEnabled('FrameworkBundle');
   

3. Where to Look First

   • BundleChecker class: Core utility for bundle operations.
   • BundleLoader class: For loading bundles dynamically.
   • BundleCollection class: Manage collections of bundles.

Implementation Patterns

Common Workflows

1. Bundle Activation/Deactivation Dynamically enable/disable bundles at runtime (useful for feature flags or modular apps):

   BundleChecker::enable('AcmeDemoBundle');
   BundleChecker::disable('AcmeDemoBundle');
   

2. Bundle Dependency Management Validate bundle dependencies before loading:

   $dependencies = BundleChecker::getDependencies('AcmeDemoBundle');
   foreach ($dependencies as $dep) {
       if (!BundleChecker::isEnabled($dep)) {
           throw new \RuntimeException("Missing dependency: {$dep}");
       }
   }
   

3. Lazy-Loading Bundles Load bundles only when needed (e.g., for plugins or optional features):

   $bundleLoader = new BundleLoader();
   $bundle = $bundleLoader->load('AcmeLazyBundle', __DIR__.'/vendor');
   

4. Bundle Collections Group related bundles for batch operations:

   $collection = new BundleCollection(['AcmeBundle1', 'AcmeBundle2']);
   $collection->enableAll();
   

Integration Tips

• Symfony Kernel Integration If using Symfony, extend the kernel to leverage BundleChecker in boot() or shutdown():

  public function boot()
  {
      if (BundleChecker::isEnabled('AcmeDebugBundle')) {
          $this->registerDebugToolbar();
      }
  }
  

• Laravel Adaptation For Laravel (non-Symfony), use the package to manage "bundles" as standalone modules:

  // Pseudocode: Treat Laravel packages as "bundles"
  if (BundleChecker::isEnabled('AcmeAnalytics')) {
      $this->loadAnalyticsService();
  }
  

• Event-Driven Workflows Trigger actions when bundles are enabled/disabled:

  BundleChecker::onEnable('AcmeBundle', function () {
      Log::info('AcmeBundle enabled!');
  });
  

Gotchas and Tips

Pitfalls

1. Symfony-Specific Assumptions

   • The package assumes a Symfony-like bundle structure (Bundle classes extending Bundle). In Laravel, you’ll need to adapt the logic (e.g., treat packages as "bundles").
   • Fix: Override BundleChecker::isEnabled() to check Laravel’s config('app.enabled_packages') or similar.

2. Circular Dependencies

   • BundleChecker::getDependencies() may not handle circular dependencies gracefully.
   • Fix: Implement a depth-limited dependency resolver or use a third-party library like symfony/dependency-injection.

3. Namespace Collisions

   • If bundles share namespaces (e.g., AcmeBundle vs. Acme\Bundle), the package may misidentify them.
   • Fix: Use fully qualified bundle names (e.g., Acme\Bundle\DemoBundle).

4. Performance Overhead

   • Scanning for bundles (BundleChecker::getAll()) can be slow in large apps.
   • Fix: Cache results or limit scans to relevant directories.

Debugging Tips

• Verify Bundle Paths Use BundleLoader::findBundle() to debug missing bundles:

  $path = BundleLoader::findBundle('AcmeBundle');
  if (!$path) {
      throw new \RuntimeException("Bundle not found!");
  }
  

• Enable Verbose Logging Temporarily enable debug mode in BundleChecker:

  BundleChecker::setDebug(true);
  

Extension Points

1. Custom Bundle Resolvers Extend BundleLoader to support non-standard bundle formats:

   class CustomBundleLoader extends BundleLoader {
       public function loadCustomBundle(string $name): object {
           // Custom logic here
       }
   }
   

2. Hook into Bundle Lifecycle Override BundleChecker::onEnable()/onDisable() to add custom logic:

   BundleChecker::onEnable('AcmeBundle', function () {
       // Post-enable logic
   });
   

3. Add Bundle Metadata Extend the package to support custom metadata (e.g., version, author):

   BundleChecker::addMetadata('AcmeBundle', ['version' => '1.0.0']);
   

Config Quirks

• No Default Configuration The package is zero-config, but you may need to set a custom bundles_path:

  BundleLoader::setBundlesPath(__DIR__.'/custom_bundles');