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 parameters.yaml to point to your config file:

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

3. Enable services: Add to config/packages/_your_bundle_name_/services.yaml:

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

4. Activate polyfills: Set active: true for desired polyfills in your config.yaml.

First Use Case

Generate a polyfill script URL dynamically in Twig:

{% set polyfillUrl = get_front_polyfill_list('js') %}
<script>
    let neededPolyfills = [];
    {{ polyfillUrl }}
        .filter(p => p.test())
        .forEach(p => neededPolyfills.push(p.name));
    if (neededPolyfills.length) {
        document.write('<script src="js/' + neededPolyfills.join('-') + '.js"><\/script>');
    }
</script>

Implementation Patterns

Workflow: Dynamic Polyfill Loading

1. Configure polyfills in config.yaml:

   polyfills:
       domch:
           active: true
           test: "!('querySelector' in document)"
           file: "path/to/domch-polyfill.js"
   

2. Generate polyfill list in Twig:

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

3. Load polyfills dynamically:

   <script>
       {{ polyfills|raw }}
           .filter(p => p.test())
           .forEach(p => {
               const script = document.createElement('script');
               script.src = `js/${p.name}.js`;
               document.head.appendChild(script);
           });
   </script>
   

Integration with Symfony Routes

1. Define a route for polyfill files:

   # config/routes.yaml
   cws_front_polyfill:
       path: /js/polyfill-{polyfill_list}.js
       controller: Cws\FrontPolyfillBundle\Controller\PolyfillController::content
   

2. Render polyfill content in Twig:

   {{ get_front_polyfill_content()|raw }}
   

Customizing Output

• Rename properties in the output array:

  {{ get_front_polyfill_list('js', 'customTest', 'customName') }}
  

  Outputs:

  [{ "customTest": test1, "customName": "test1" }, ...]
  

Caching Strategy

• Generate static files for performance:

  <script src="js/polyfill-domch-eachnl.js"></script>
  

  • Use get_front_polyfill_content() in a Twig template for /js/polyfill-{polyfill_list}.js.
  • Clear generated files on cache warmup:

    php bin/console cache:clear --env=prod --no-debug
    rm -f var/cache/prod/js/polyfill-*.js
    

Gotchas and Tips

Pitfalls

1. Route Placeholder Mismatch:

   • Ensure the route placeholder (polyfill_list) matches the config:

     parameters:
         cws.polyfill.route_placeholder: polyfill_list  # Default; omit if using default
     

   • Example route: /js/polyfill-{polyfill_list}.js.

2. Twig Auto-escaping:

   • Use |raw to prevent escaping in get_front_polyfill_list() output:

     {{ get_front_polyfill_list('js')|raw }}
     

3. Query String vs. Filename:

   • Query string method (?polyfill1&polyfill2) is less cache-friendly.
   • Filename method (polyfill-polyfill1-polyfill2.js) is preferred for static files.

4. Config Path Overrides:

   • If config_path is misconfigured, polyfills won’t load. Verify:

     parameters:
         cws.polyfill.config_path: /correct/path/to/config.yaml
     

Debugging

• Check active polyfills:

  $polyfills = $this->get('cws_front_polyfill.config')->getActivePolyfills();
  dump($polyfills);
  

• Validate tests: Ensure polyfill tests return true/false (or truthy/falsy values) in the browser console:

  console.log(polyfill.test()); // Should log `true` or `false`
  

Extension Points

1. Custom Polyfill Tests: Extend the config schema to support custom test logic:

   polyfills:
       custom:
           test: "@service_id.method"  # Call a service method for dynamic tests
   

   • Requires implementing Cws\FrontPolyfillBundle\Polyfill\TestInterface.

2. Dynamic Polyfill Loading: Use JavaScript to load polyfills asynchronously:

   <script>
       (function() {
           const polyfills = {{ get_front_polyfill_list('js')|raw }};
           polyfills.forEach(p => {
               if (p.test) {
                   const script = document.createElement('script');
                   script.src = `js/${p.name}.js`;
                   script.onload = () => console.log(`${p.name} loaded`);
                   document.head.appendChild(script);
               }
           });
       })();
   </script>
   

3. Polyfill Bundling: Combine polyfills into a single file for production:

   • Use a build tool (Webpack, Vite) to concatenate js/polyfill-*.js files.
   • Example Webpack config:

     module.exports = {
         entry: './var/cache/prod/js/polyfill-*.js',
         output: {
             filename: 'polyfills.bundle.js',
             path: './public/js'
         }
     };
     

Performance Tips

• Pre-generate polyfill files: Run a post-install script to generate common polyfill combinations:

  php bin/console cws:polyfill:generate --polyfills="domch,eachnl"
  

• Lazy-load polyfills: Load polyfills only when needed (e.g., on feature-specific pages):

  {% if app.request.get('feature') == 'picture' %}
      <script src="js/polyfill-picture.js"></script>
  {% endif %}
  

Configuration Quirks

• Boolean vs. String Tests: The config supports both:

  polyfills:
      simple:
          test: true  # Static true/false
      dynamic:
          test: "!('fetch' in window)"  # Dynamic JS expression
  

• File Paths: Polyfill files must be accessible via public/ or a configured web directory. Use absolute paths in config.yaml:

  polyfills:
      domch:
          file: "%kernel.project_dir%/public/js/polyfills/domch.js"