Polyfill Symfony Framework Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require sylius-labs/polyfill-symfony-framework-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       SyliusLabs\PolyfillSymfonyFrameworkBundle\PolyfillSymfonyFrameworkBundle::class => ['all' => true],
   ];
   

2. First Use Case:

   • Use this bundle when your project relies on Symfony FrameworkBundle features (e.g., ContainerAwareCommand, HttpKernel, or other deprecated/removed components) but is not using Symfony FrameworkBundle directly (e.g., in a standalone Laravel app or a project with a custom kernel).
   • Example: If you need ContainerAwareCommand (removed in Symfony 5+) but are using Symfony components outside the full framework.

Implementation Patterns

Workflow Integration

1. Polyfilling Symfony Components:

   • Replace direct Symfony FrameworkBundle dependencies with this bundle. For example:

     // Instead of:
     use Symfony\Component\HttpKernel\KernelInterface;
     
     // Use the polyfilled version (if available):
     use SyliusLabs\PolyfillSymfonyFrameworkBundle\DependencyInjection\ContainerAwareCommand; // Hypothetical example
     

   • Check the bundle’s source for supported polyfills (e.g., ContainerAwareCommand, HttpKernel traits).

2. Laravel-Specific Use Cases:

   • Commands: Polyfill ContainerAwareCommand to integrate Symfony-style commands in Laravel:

     use SyliusLabs\PolyfillSymfonyFrameworkBundle\Command\ContainerAwareCommand;
     
     class MyCommand extends ContainerAwareCommand {
         protected function execute(InputInterface $input, OutputInterface $output) {
             $this->getContainer()->get('some.service');
         }
     }
     

   • Kernel Integration: Use the polyfilled HttpKernel to bridge Symfony HTTP logic into Laravel middleware or routes.

3. Dependency Injection:

   • Leverage Symfony’s DI container via the polyfill to access services or configure Laravel’s service container:

     $container = $this->getContainer(); // From ContainerAwareCommand
     $service = $container->get('app.some_service');
     

4. Configuration:

   • Extend Laravel’s config/services.php or config/kernel.php to include polyfilled Symfony configurations:

     'framework' => [
         'polyfill' => [
             'enabled' => env('SYMFONY_POLYFILL_ENABLED', true),
             // Custom polyfill settings
         ],
     ],
     

Gotchas and Tips

Pitfalls

1. Symfony Version Mismatch:

   • The bundle supports Symfony 5.4+ (as of v1.1.0). Ensure your composer.json aligns with this:

     "require": {
         "symfony/framework-bundle": "^5.4|^6.0"
     }
     

   • Error: Using Symfony 4.x will break the bundle (see #1).

2. Namespace Conflicts:

   • Avoid naming collisions with Symfony’s original classes. Prefix or alias polyfilled classes:

     use SyliusLabs\PolyfillSymfonyFrameworkBundle\Command\ContainerAwareCommand as PolyfillContainerAwareCommand;
     

3. Mbstring Polyfill Conflict:

   • The bundle removes conflicts with symfony/polyfill-mbstring (fixed in v1.1.1). Ensure you’re not double-polyfilling:

     composer remove symfony/polyfill-mbstring
     

4. Deprecated Features:

   • Some polyfills (e.g., ContainerAwareCommand) are deprecated in Symfony 6. Use at your own risk or migrate to alternatives like Command with explicit container access.

Debugging Tips

1. Enable Debug Mode: Add to config/services.php:

   'framework' => [
       'polyfill' => [
           'debug' => env('APP_DEBUG', false),
       ],
   ],
   

   This may expose polyfill-specific errors in Laravel’s debug bar.

2. Check Polyfill Coverage:

   • The bundle’s source lists supported classes. If a feature is missing, consider:
     • Forking the repo to add support.
     • Using Symfony’s official polyfills (e.g., symfony/polyfill-*).

3. Container Initialization:

   • If the polyfill fails to initialize, ensure your Laravel service provider bootstraps the Symfony container:

     public function boot() {
         if ($this->app->has('polyfill_symfony_framework')) {
             $this->app->boot();
         }
     }
     

Extension Points

1. Custom Polyfills:

   • Extend the bundle by creating a child class for missing polyfills. Example:

     namespace App\Polyfills;
     
     use SyliusLabs\PolyfillSymfonyFrameworkBundle\PolyfillSymfonyFrameworkBundle as BaseBundle;
     
     class CustomPolyfillBundle extends BaseBundle {
         public function getPolyfills() {
             return array_merge(parent::getPolyfills(), [
                 'App\Polyfills\MyMissingClass' => 'Symfony\Component\Some\MissingClass',
             ]);
         }
     }
     

   • Register it in config/bundles.php.

2. Symfony Flex Integration:

   • The bundle supports Symfony Flex (added in v1.1.0). Use symfony/flex recipes to automate polyfill configuration:

     composer require symfony/flex