Device Detector Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require acsiomatic/device-detector-bundle
   

   Enable the bundle in config/bundles.php (auto-enabled in Symfony 5+).

2. First Use Case: Inject the DeviceDetector service into a controller to detect the current user's device:

   use Acsiomatic\DeviceDetectorBundle\DeviceDetector;
   
   public function index(DeviceDetector $detector)
   {
       $device = $detector->parse($_SERVER['HTTP_USER_AGENT']);
       dd($device->isMobile(), $device->getClientName());
   }
   

3. Twig Integration: Access the device global variable directly in templates:

   {% if device.isMobile() %}
       <link rel="stylesheet" href="{{ asset('mobile.css') }}">
   {% endif %}
   

Implementation Patterns

Core Workflows

1. Request-Based Detection: Parse the current request’s user agent in controllers or services:

   public function show(Request $request, DeviceDetector $detector)
   {
       $device = $detector->parseRequest($request);
       // Use $device->isTablet(), $device->getOs(), etc.
   }
   

2. Route Conditions: Restrict routes to specific devices (e.g., mobile-only):

   # config/routes.yaml
   mobile_route:
       path: /mobile
       controller: App\Controller\MobileController::index
       requirements:
           device: mobile
   

   Add a route loader service (see usage docs).

3. Batch Processing: Parse user agents in bulk (e.g., for analytics):

   $userAgents = ['Mozilla/5.0...', 'AppleWebKit/...'];
   $detector->parseMultiple($userAgents);
   

Integration Tips

• Caching: Enable auto_parse: true (default) to cache parsed results for the request lifecycle.
• Client Hints: Use parseClientHints() for modern browsers supporting Client Hints.
• Custom Logic: Extend the DeviceDetector service by binding a custom class:

  # config/services.yaml
  Acsiomatic\DeviceDetectorBundle\DeviceDetector: '@custom.device_detector'
  

Gotchas and Tips

Pitfalls

1. User Agent Spoofing: User agents can be faked. Validate results with additional logic (e.g., IP-based heuristics).

2. Performance: Parsing is lightweight, but avoid parsing the same user agent repeatedly in loops. Cache results:

   $cacheKey = 'device_'.$_SERVER['HTTP_USER_AGENT'];
   $device = $cache->get($cacheKey) ?? $detector->parse($_SERVER['HTTP_USER_AGENT']);
   

3. Route Conditions: The device route requirement is case-sensitive (mobile vs. Mobile). Use lowercase consistently.

Debugging

• Verify Parsing: Check raw output for debugging:

  dd($detector->parse($_SERVER['HTTP_USER_AGENT'])->getData());
  

• Update Rules: The underlying DeviceDetector library updates rules via composer update. Run:

  composer update matomo-org/device-detector
  

Extension Points

1. Custom Device Rules: Extend the parser by overriding the DeviceDetector service and modifying its getParser() method.

2. Twig Extensions: Add custom Twig filters/filters:

   // src/Twig/AppExtension.php
   public function getFilters()
   {
       return [
           new \Twig\TwigFilter('is_ios', [$this, 'isIosDevice']),
       ];
   }
   

3. Configuration Quirks:

   • auto_parse: false disables automatic parsing; manually call parse().
   • version_truncation: Set to minor or major to control version string length (default: minor). Example:

     acsiomatic_device_detector:
         version_truncation: major