Front Polyfill Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require creative-web-solution/front-polyfill-bundle
   

2. Configure the bundle:
   • Copy Resources/sample/config.yaml to your project (e.g., /frontend/polyfill/config.yaml).
   • Update config/packages/cws_front_polyfill.yaml with your custom path if needed:

     parameters:
         cws.polyfill.config_path: /frontend/polyfill/config.yaml
     

3. Enable services: Add to config/bundles.php:

   return [
       // ...
       Cws\FrontPolyfillBundle\CwsFrontPolyfillBundle::class => ['all' => true],
   ];
   

   Or import services in config/services.yaml:

   imports:
       - { resource: '@CwsFrontPolyfillBundle/Resources/config/services.xml' }
   

First Use Case: Basic Polyfill Injection

Generate a polyfill script URL dynamically in a Twig template:

<script src="{{ path('cws_front_polyfill', {
    'polyfill_list': get_front_polyfill_list('js')|join('-')
}) }}"></script>

Ensure your route (cws_front_polyfill) has a placeholder named polyfill_list (configurable via cws.polyfill.route_placeholder).

Implementation Patterns

Workflow: Dynamic Polyfill Loading

1. Configure polyfills in config.yaml:

   polyfills:
       domch:
           test: "@=feature-detection.test('dom-ch')"
           active: true
       picture:
           test: "@=feature-detection.test('picture')"
           active: false
   

2. Generate polyfill list in Twig:

   {% set polyfills = get_front_polyfill_list('js') %}
   

3. Load polyfills dynamically:

   <script>
       const polyfillUrl = `/js/${polyfills|map(attribute='name')|join('-')}.js`;
       if (polyfillUrl) {
           document.head.appendChild(Object.assign(document.createElement('script'), {
               src: polyfillUrl,
               async: false
           }));
       }
   </script>
   

Integration Tips

• Symfony Flex: Use config/packages/cws_front_polyfill.yaml for environment-specific configs.
• Cache Optimization:
  • Generate polyfill files during build (e.g., make:polyfills command) and cache them.
  • Clear generated files on cache warmup:

    // In a command or event listener
    $this->container->get('cws_front_polyfill.file_manager')->clearGeneratedFiles();
    

• Feature Detection: Pair with libraries like @babel/polyfill or core-js for runtime checks.

Advanced: Custom Polyfill Routes

Override the default route placeholder in config/packages/cws_front_polyfill.yaml:

parameters:
    cws.polyfill.route_placeholder: 'pf_list'  # Custom placeholder

Update your route definition:

# config/routes.yaml
cws_front_polyfill:
    path: /assets/polyfills/{pf_list}.js
    defaults: { _controller: 'CwsFrontPolyfillBundle:Polyfill:content' }

Gotchas and Tips

Pitfalls

1. Route Placeholder Mismatch:

   • Error: No route found for "GET /js/polyfill-domch.js".
   • Fix: Ensure the route placeholder (polyfill_list by default) matches the generated filename.
   • Debug: Check config/packages/cws_front_polyfill.yaml for route_placeholder.

2. Circular Dependencies:

   • Error: Polyfill files regenerate on every request due to missing cache headers.
   • Fix: Explicitly cache generated files:

     {% cache until(timestamp('+1 year')) %}
         {{ get_front_polyfill_content()|raw }}
     {% endcache %}
     

3. Query String vs. Filename:

   • Gotcha: Query strings (?pf1&pf2) are less cache-friendly than filenames (pf1-pf2.js).
   • Tip: Prefer filename-based loading for production.

Debugging

• Verify Active Polyfills:

  // Dump active polyfills in a controller
  dd($this->container->get('cws_front_polyfill.manager')->getActivePolyfills());
  

• Check Generated Files:

  # List generated polyfill files
  find var/cache -name "*polyfill*.js"
  

• Log Polyfill Tests: Enable debug mode in config.yaml:

  debug:
      log_tests: true  # Logs test results to Symfony profiler
  

Extension Points

1. Custom Polyfill Tests: Extend the Cws\FrontPolyfillBundle\Manager\PolyfillManager service to add custom tests:

   // src/Service/PolyfillTestExtension.php
   use Cws\FrontPolyfillBundle\Manager\PolyfillManagerInterface;
   
   class PolyfillTestExtension implements PolyfillManagerInterface
   {
       public function getTest(string $name): mixed
       {
           return match($name) {
               'custom-polyfill' => function() { return !!window.customFeature; },
               default => $this->decorated->getTest($name),
           };
       }
   }
   

   Register as a decorator in config/services.yaml:

   services:
       Cws\FrontPolyfillBundle\Manager\PolyfillManager:
           decorates: 'cws_front_polyfill.manager'
           arguments: ['@.inner']
   

2. Dynamic Config Loading: Override Cws\FrontPolyfillBundle\Config\ConfigLoader to load polyfills from a database or API:

   // src/Config/DynamicConfigLoader.php
   use Cws\FrontPolyfillBundle\Config\ConfigLoaderInterface;
   
   class DynamicConfigLoader implements ConfigLoaderInterface
   {
       public function load(): array
       {
           return $this->fetchFromDatabaseOrApi();
       }
   }
   

   Bind it in services.yaml:

   services:
       Cws\FrontPolyfillBundle\Config\ConfigLoader:
           class: App\Config\DynamicConfigLoader
   

3. Polyfill Content Filters: Modify the output of get_front_polyfill_content() by extending the PolyfillContentRenderer:

   // src/Twig/PolyfillContentRenderer.php
   use Cws\FrontPolyfillBundle\Twig\PolyfillContentRenderer as BaseRenderer;
   
   class PolyfillContentRenderer extends BaseRenderer
   {
       public function __invoke(array $polyfills, string $mode = 'file'): string
       {
           $content = parent::__invoke($polyfills, $mode);
           return $this->addCustomFooter($content);
       }
   
       private function addCustomFooter(string $content): string
       {
           return $content . "\n// Custom footer";
       }
   }
   

   Override the Twig function in services.yaml:

   services:
       cws_front_polyfill.twig.polyfill_content:
           class: App\Twig\PolyfillContentRenderer
           tags: ['twig.extension']