Browserslist Check Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require barthy-koeln/browserslist-check-bundle
   

   Add to config/bundles.php if not auto-discovered:

   Barthy\BrowserslistCheckBundle\BrowserslistCheckBundle::class => ['all' => true],
   

2. Configure .browserslistrc Place a .browserslistrc file in your project root with a [modern] section (e.g., as shown in the README). Example:

   [modern]
   Chrome >= 97
   Firefox >= 91
   

3. First Use Case: Serve Conditional Assets Use the Twig extension to check the user's browser and serve optimized builds:

   {% if app.browserslist_check.is_modern() %}
       {{ encore_entry_link_tags('app-modern') }}
   {% else %}
       {{ encore_entry_link_tags('app-legacy') }}
   {% endif %}
   

Implementation Patterns

Core Workflows

1. Browser Detection in Controllers Inject the service and use it for logic branching:

   use Barthy\BrowserslistCheckBundle\BrowserslistCheck;
   
   public function index(BrowserslistCheck $check)
   {
       if ($check->isModern()) {
           return $this->render('modern.html.twig');
       }
       return $this->render('legacy.html.twig');
   }
   

2. Dynamic Asset Loading Combine with Encore to conditionally load scripts/styles:

   {% if app.browserslist_check.is_modern() %}
       {{ encore_entry_script_tags('modern') }}
   {% else %}
       {{ encore_entry_script_tags('legacy') }}
   {% endif %}
   

3. Caching Strategies The bundle caches the parsed .browserslistrc during Symfony cache warmup. Avoid runtime parsing by ensuring:

   • The file is committed to version control.
   • Cache is rebuilt after changes (php bin/console cache:clear).

4. Integration with Symfony’s HTTP Cache Use the service to vary responses by browser capability:

   $response = new Response($content);
   $response->setPublic();
   $response->setVary('X-Browser-Capability');
   

Advanced Patterns

• Custom Rulesets Extend the bundle to support additional rulesets (e.g., [fast], [slow]):

  // src/Service/BrowserChecker.php
  $checker->addRuleset('fast', ['Chrome >= 100', 'Firefox >= 100']);
  

• Event-Based Logic Trigger actions based on browser detection (e.g., analytics, feature flags):

  use Symfony\Component\HttpKernel\Event\RequestEvent;
  
  public function onKernelRequest(RequestEvent $event)
  {
      if (!$event->isMainRequest()) return;
      $check = $event->getRequest()->get('browserslist_check');
      if ($check->isModern()) {
          $this->analytics->track('modern_browser');
      }
  }
  

Gotchas and Tips

Pitfalls

1. .browserslistrc Parsing Quirks

   • Order Matters: The [modern] section must be first. Misordering breaks detection.
   • Syntax Strictness: Only >= is supported in the [modern] section. Use > or < in other sections (e.g., [legacy]).
   • Unsupported Browsers: The underlying library (donatj/PhpUserAgent) may not recognize niche browsers (e.g., older Samsung browsers). Test edge cases.

2. Caching Issues

   • Cache Invalidation: After modifying .browserslistrc, clear Symfony’s cache:

     php bin/console cache:clear
     

   • Debug Mode: In config/packages/dev/browserslist_check.yaml, set debug: true to bypass cache and log parsed rules.

3. User-Agent Spoofing

   • Bots/Crawlers: The bundle recognizes some crawlers (e.g., Googlebot) as "modern" by default. Override in config:

     # config/packages/browserslist_check.yaml
     barthy_browserslist_check:
         recognized_crawlers: ['*']  # Treat all as modern/legacy
     

4. Performance Overhead

   • Avoid Runtime Parsing: The bundle caches the config, but parsing still occurs on first request. For high-traffic sites, pre-warm the cache:

     php bin/console cache:warmup --env=prod
     

Debugging Tips

1. Inspect Parsed Rules Dump the parsed config in a controller:

   dump($this->container->get('browserslist_check')->getRules());
   

   Outputs an array like:

   [
       'modern' => [
           'Chrome' => 97,
           'Firefox' => 91,
           // ...
       ],
       'legacy' => ['defaults', 'ie 11', ...],
   ]
   

2. Log User-Agent Matches Enable debug logging in config/packages/dev/browserslist_check.yaml:

   barthy_browserslist_check:
       debug: true
   

   Check logs for entries like:

   [BrowserslistCheck] User-Agent matched: Chrome 100 → modern
   

3. Test with Real User-Agents Use tools like User-Agent Switcher to verify detection works across browsers.

Extension Points

1. Custom User-Agent Parsing Override the default parser by binding a custom service:

   # config/services.yaml
   services:
       Barthy\BrowserslistCheckBundle\Parser\UserAgentParserInterface: '@App\Service\CustomUserAgentParser'
   

2. Add New Rulesets Extend the bundle’s RulesetManager to support additional sections:

   // src/Service/RulesetManager.php
   public function addRuleset(string $name, array $rules): void
   {
       $this->rulesets[$name] = $rules;
   }
   

   Then use in Twig:

   {% if app.browserslist_check.is('fast') %}
       {{ encore_entry_script_tags('fast') }}
   {% endif %}
   

3. Symfony Flex Integration If using Symfony Flex, ensure the bundle’s config is merged correctly. Override defaults in:

   # config/packages/browserslist_check.yaml
   barthy_browserslist_check:
       modern_ruleset: 'custom_modern'  # Rename the default ruleset