Browscap Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cravler/browscap-bundle
   

   Add the bundle to config/bundles.php (Laravel 5.4+) or AppKernel.php (Symfony/Laravel <5.4):

   // config/bundles.php
   return [
       // ...
       Cravler\BrowscapBundle\BrowscapBundle::class => ['all' => true],
   ];
   

2. Publish Config (optional):

   php artisan vendor:publish --tag=browscap-config
   

   This creates config/browscap.php with default settings.

3. First Use Case: Inject the Browscap service and fetch browser info from a user-agent string:

   use Cravler\BrowscapBundle\Browscap\Browscap;
   
   public function detectBrowser(Browscap $browscap)
   {
       $userAgent = request()->userAgent();
       $browser = $browscap->getBrowser($userAgent);
   
       return $browser->getBrowser() . ' ' . $browser->getVersion();
   }
   

Implementation Patterns

Core Workflows

1. Fetching Browser Data:

   // Get full Browscap object
   $browser = $browscap->getBrowser($userAgent);
   
   // Access specific properties
   $browser->getBrowser();       // e.g., "Chrome"
   $browser->getVersion();       // e.g., "91.0.4472.124"
   $browser->getPlatform();      // e.g., "Windows"
   $browser->getMajorver();      // e.g., "91"
   

2. Caching Strategy: The bundle auto-caches results for 24 hours by default. Override in config:

   'cache' => [
       'enabled' => true,
       'ttl' => 3600, // 1 hour
   ],
   

3. Remote vs. Local INI:

   • Remote: Fetches latest data from browscap.org (default).

     'remote_ini_url' => 'http://tempdownloads.browserscap.com/stream.php?BrowsCapINI',
     

   • Local: Use a self-hosted INI file (recommended for production):

     'local_ini_path' => storage_path('browscap/browscap.ini'),
     

     Download the INI from browscap.org and place it in storage/browscap/.

4. Middleware Integration: Attach to middleware to enrich requests with browser data:

   namespace App\Http\Middleware;
   
   use Closure;
   use Cravler\BrowscapBundle\Browscap\Browscap;
   
   class DetectBrowser
   {
       protected $browscap;
   
       public function __construct(Browscap $browscap)
       {
           $this->browscap = $browscap;
       }
   
       public function handle($request, Closure $next)
       {
           $browser = $this->browscap->getBrowser($request->userAgent());
           $request->merge(['browser' => $browser]);
   
           return $next($request);
       }
   }
   

5. Custom Logic: Extend the Browscap service or create a decorator:

   class CustomBrowscap extends Browscap
   {
       public function isMobile($userAgent)
       {
           $browser = $this->getBrowser($userAgent);
           return in_array($browser->getPlatform(), ['iOS', 'Android', 'Windows Phone']);
       }
   }
   

Gotchas and Tips

Pitfalls

1. Rate Limiting: Remote INI fetching may hit rate limits if called frequently. Use local INI in production:

   'remote_ini_url' => null, // Disable remote fetching
   'local_ini_path' => storage_path('browscap/browscap.ini'),
   

2. Outdated Data: The free Browscap INI updates weekly. For critical apps, consider:

   • A paid license for real-time updates.
   • A cron job to auto-update the local INI:

     * * * * * cd /path/to/project && php artisan browscap:update
     

3. User-Agent Spoofing: Malicious users can spoof user-agent strings. Validate critical data server-side:

   if ($browser->getBrowser() === 'Unknown') {
       // Handle unknown browsers or potential spoofing
   }
   

4. Memory Usage: The Browscap INI is ~1MB. For high-traffic apps, ensure your server has enough memory.

5. Deprecation: The get_browser() PHP function is deprecated. This bundle is a modern alternative but may evolve independently.

Debugging

1. Check Cache: Clear cache if data seems stale:

   php artisan cache:clear
   php artisan config:clear
   

2. Log User-Agent: Debug mismatches by logging raw user-agent strings:

   \Log::debug('User-Agent:', [$request->userAgent()]);
   

3. Validate INI File: Ensure the local INI file is readable and valid:

   php artisan browscap:validate
   

Extension Points

1. Custom Properties: Extend the Browscap\Browscap\Browser class to add custom methods:

   namespace App\Extensions;
   
   use Cravler\BrowscapBundle\Browscap\Browser;
   
   class ExtendedBrowser extends Browser
   {
       public function isSupported()
       {
           return !in_array($this->getBrowser(), ['IE', 'Edge']);
       }
   }
   

2. Event Listeners: Listen for Browscap updates or failures:

   // config/browscap.php
   'events' => [
       'update.success' => [YourListener::class, 'onUpdateSuccess'],
       'update.failure' => [YourListener::class, 'onUpdateFailure'],
   ],
   

3. Testing: Mock the Browscap service in tests:

   $mockBrowser = new \Cravler\BrowscapBundle\Browscap\Browser();
   $mockBrowser->setBrowser('Chrome')->setVersion('91.0');
   
   $mockBrowscap = $this->createMock(Browscap::class);
   $mockBrowscap->method('getBrowser')->willReturn($mockBrowser);