Distribution Bundle Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation via Composer Add the bundle to your Laravel project (via Symfony bridge or standalone) by requiring it in composer.json:

   composer require symfony/distribution-bundle
   

   Note: Since Laravel doesn’t natively support Symfony bundles, use a bridge like symfony/var-dumper or integrate via a custom service provider.

2. First Use Case: Bootstrap a Symfony-like Structure Use the bundle’s Sensio\Bundle\DistributionBundle\SensioDistributionBundle to scaffold a Laravel project with Symfony conventions (e.g., app/config, web/app.php). Override Laravel’s default structure by:

   • Publishing assets:

     php artisan vendor:publish --provider="Sensio\Bundle\DistributionBundle\SensioDistributionBundle" --tag=config
     

   • Configuring config/app.php to mirror Symfony’s AppKernel.php logic (e.g., bundle registration).

3. Key Files to Inspect

   • Resources/config/config.xml: Default Symfony distribution config (adapt for Laravel).
   • SensioDistributionBundle.php: Entry point for bundle logic.

Implementation Patterns

Workflows for Laravel Integration

1. Bundle Registration Extend Laravel’s service container to load Symfony bundles:

   // config/app.php
   'providers' => [
       // ...
       Sensio\Bundle\DistributionBundle\SensioDistributionBundle::class,
       // Custom bridge provider to adapt Symfony services to Laravel
   ];
   

2. Configuration Overrides Use Laravel’s config system to override Symfony defaults:

   // config/sensio_distribution.php
   return [
       'framework' => [
           'router' => [
               'resource' => '%kernel.root_dir%/config/routing.yml', // Symfony-style routing
               'strict_requirements' => env('ROUTING_STRICT', true),
           ],
       ],
   ];
   

3. Asset Management Leverage Symfony’s asset system for Laravel:

   // app/Providers/AppServiceProvider.php
   use Sensio\Bundle\FrameworkExtraBundle\Asset\Packages;
   public function register()
   {
       $this->app->singleton(Packages::class, function () {
           return new Packages($this->app['kernel']->getRootDir() . '/public');
       });
   }
   

4. Debugging Tools Integrate Symfony’s profiler (e.g., WebProfilerBundle) for Laravel:

   composer require symfony/web-profiler-bundle
   

   Configure in config/app.php and use middleware to inject the toolbar.

5. Environment-Specific Configs Use Laravel’s .env to toggle Symfony features:

   APP_DEBUG=true
   SENSIO_DISTRIBUTION_ENABLED=true
   

Gotchas and Tips

Pitfalls and Debugging

1. Namespace Collisions

   • Symfony bundles assume src/ and App/ namespaces. In Laravel, alias these in composer.json:

     "autoload": {
         "psr-4": {
             "App\\": "app/",
             "Sensio\\": "vendor/sensio/"
         }
     }
     

   • Tip: Use use statements with fully qualified names (e.g., Sensio\Bundle\...) to avoid ambiguity.

2. Routing Conflicts

   • Symfony’s routing.yml may clash with Laravel’s routes/web.php. Merge them:

     # config/routing.yml (Symfony-style)
     app:
         resource: "@AppBundle/Resources/config/routing.yml"
         prefix: /
     

   • Tip: Use Laravel’s RouteServiceProvider to preload Symfony routes:

     public function boot()
     {
         parent::boot();
         $loader = new YamlFileLoader($this->app['filesystem'], new FileLocator());
         $loader->load($this->app['kernel']->getRootDir() . '/config/routing.yml');
     }
     

3. Dependency Injection Quirks

   • Symfony’s DI container (ContainerInterface) differs from Laravel’s. Bridge them:

     $symfonyContainer = new SymfonyContainer();
     $this->app->instance('symfony.container', $symfonyContainer);
     

   • Tip: Use symfony/dependency-injection to create a hybrid container.

4. Asset Pipeline Issues

   • Symfony’s asset() helper may not resolve Laravel’s public/ path. Override:

     // app/Providers/AppServiceProvider.php
     use Sensio\Bundle\FrameworkExtraBundle\Asset\AssetManager;
     public function boot()
     {
         $assetManager = $this->app->make(AssetManager::class);
         $assetManager->setPublicPath($this->app->basePath() . '/public');
     }
     

5. Debugging the Profiler

   • If the WebProfiler toolbar doesn’t appear, ensure:
     • APP_DEBUG=true in .env.
     • Middleware is registered:

       $this->app->middleware(Sensio\Bundle\FrameworkExtraBundle\EventListener\WebProfilerMiddleware::class);
       

   • Tip: Clear Laravel’s cache after adding Symfony bundles:

     php artisan cache:clear
     php artisan config:clear
     

6. Extension Points

   • Custom Bundles: Create Laravel-specific bundles that extend Symfony bundles (e.g., App\SensioBundle).
   • Event Listeners: Override Symfony events in Laravel’s EventServiceProvider:

     protected $listen = [
         'kernel.request' => [
             'Sensio\Bundle\FrameworkExtraBundle\EventListener\RouterListener::onKernelRequest',
         ],
     ];
     

   • Templates: Use Symfony’s Twig integration with Laravel’s Blade via symfony/twig-bridge.

7. Performance Notes

   • Symfony’s autoloader may slow Laravel. Optimize with:

     composer dump-autoload --optimize
     

   • Exclude Symfony’s dev dependencies in production:

     composer install --no-dev