Symfony Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require boson-php/symfony-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Boson\SymfonyBundle\BosonBundle::class => ['all' => true],
   ];
   

2. Configure Boson Runtime Publish the default config:

   php bin/console boson:install
   

   Edit config/packages/boson.yaml to define your Boson runtime (e.g., boson.runtime key).

3. First Use Case: Dynamic Service Resolution Register a Boson service in services.yaml:

   services:
       App\Services\DynamicService:
           tags: ['boson.service']
   

   Resolve it dynamically in a controller:

   use Boson\SymfonyBundle\BosonRuntime;
   
   class MyController extends AbstractController {
       public function __invoke(BosonRuntime $boson): Response {
           $service = $boson->get('App\Services\DynamicService');
           return new Response($service->execute());
       }
   }
   

Implementation Patterns

Core Workflows

1. Runtime-Agnostic Service Binding Use Boson to resolve services without Symfony’s container:

   $runtime = $this->get(BosonRuntime::class);
   $service = $runtime->get('my.service'); // Resolves via Boson, not Symfony DI
   

2. Middleware Integration Attach Boson middleware to Symfony’s kernel:

   # config/packages/boson.yaml
   boson:
       middleware:
           - Boson\SymfonyBundle\Middleware\AuthMiddleware
   

3. Event-Driven Architecture Dispatch Boson events globally:

   $boson->dispatch('app.event', ['data' => $payload]);
   

   Listen in a service:

   use Boson\SymfonyBundle\Events\BosonEvent;
   
   class EventListener {
       public function onBosonEvent(BosonEvent $event) {
           // Handle event
       }
   }
   

Integration Tips

• Hybrid DI: Combine Symfony DI and Boson by tagging services:

  services:
      App\Services\HybridService:
          tags: ['boson.service', 'container.service']
  

• Configuration Overrides: Use boson.yaml to override Boson’s default behavior (e.g., boson.runtime.path).
• Testing: Mock BosonRuntime in tests:

  $this->mock(BosonRuntime::class)->shouldReceive('get')->andReturn($mockService);
  

Gotchas and Tips

Common Pitfalls

1. Circular Dependencies Boson’s runtime resolves services lazily. Circular dependencies may cause RuntimeException:

   // ❌ Avoid:
   $serviceA = $boson->get('ServiceA'); // Depends on ServiceB
   $serviceB = $boson->get('ServiceB'); // Depends on ServiceA
   

   Fix: Use Symfony’s DI for circular cases or restructure dependencies.

2. Configuration Mismatch Ensure boson.runtime in boson.yaml matches your Boson PHP version (e.g., boson.runtime = "boson-php/boson:^1.0").

3. Middleware Order Boson middleware runs after Symfony’s kernel middleware. Reorder in boson.yaml if needed:

   boson:
       middleware:
           - Boson\SymfonyBundle\Middleware\FirstMiddleware
           - Symfony\Component\HttpKernel\Middleware\SecondMiddleware
   

Debugging Tips

• Enable Boson Logging Add to config/packages/monolog.yaml:

  handlers:
      boson:
          type: stream
          path: "%kernel.logs_dir%/boson.log"
          level: debug
  

• Inspect Runtime State Dump Boson’s resolved services:

  dump($boson->getContainer()->getServices());
  

• Clear Cache After Config Changes Boson caches runtime configurations. Run:

  php bin/console cache:clear
  

Extension Points

1. Custom Runtimes Extend BosonRuntime to add domain-specific logic:

   class AppBosonRuntime extends BosonRuntime {
       public function getAppService() {
           return $this->get('app.custom.service');
       }
   }
   

   Register in services.yaml:

   services:
       Boson\SymfonyBundle\BosonRuntime: '@AppBosonRuntime'
   

2. Service Decorators Decorate Boson services with Symfony’s decorator pattern:

   services:
       app.service.decorated:
           decorates: 'app.service'
           arguments: ['@app.service.decorated.inner']
   

3. Event Subscribers Subscribe to Boson events in Symfony’s event dispatcher:

   use Boson\SymfonyBundle\Events\BosonEvent;
   
   class BosonSubscriber implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               BosonEvent::RUNTIME_INIT => 'onRuntimeInit',
           ];
       }
   }