Wurfl Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require acasademont/wurfl-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Acasademont\WurflBundle\ACFWurflBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console acf-wurfl:install
   

   Update config/packages/acf_wurfl.yaml with your WURFL API key and other settings.

3. First Use Case Inject the WURFL service in a controller or service:

   use Acasademont\WurflBundle\Service\WurflService;
   
   class DeviceController extends AbstractController
   {
       public function __construct(private WurflService $wurfl)
       {
       }
   
       public function detect(Request $request)
       {
           $userAgent = $request->headers->get('User-Agent');
           $deviceInfo = $this->wurfl->getDeviceInfo($userAgent);
           return $this->json($deviceInfo);
       }
   }
   

Implementation Patterns

Common Workflows

1. Device Detection in Controllers

   public function showContent(Request $request)
   {
       $deviceInfo = $this->wurfl->getDeviceInfo($request->headers->get('User-Agent'));
       if ($deviceInfo['is_tablet']) {
           return $this->render('tablet_view.html.twig');
       }
       return $this->render('default_view.html.twig');
   }
   

2. Caching Responses Cache WURFL responses for performance (e.g., using Symfony Cache component):

   $cacheKey = md5($userAgent);
   $deviceInfo = $this->cache->get($cacheKey, function() use ($userAgent) {
       return $this->wurfl->getDeviceInfo($userAgent);
   });
   

3. Custom Capability Checks Extend the bundle to add custom logic:

   $capabilities = $this->wurfl->getCapabilities($userAgent);
   if ($capabilities['flash_lite'] && $capabilities['resolution_width'] > 1024) {
       // High-res Flash Lite device
   }
   

4. Integration with Symfony Events Use the kernel.request event to auto-detect devices:

   $eventDispatcher->addListener(KernelEvents::REQUEST, function (RequestEvent $event) {
       $request = $event->getRequest();
       $request->attributes->set('device_info', $this->wurfl->getDeviceInfo($request->headers->get('User-Agent')));
   });
   

5. Bulk Processing Process multiple user agents (e.g., for analytics):

   $userAgents = ['Mozilla/5.0...', 'AppleWebKit/...'];
   $results = $this->wurfl->batchDetect($userAgents);
   

Gotchas and Tips

Pitfalls

1. API Key Management

   • Never commit your WURFL API key to version control. Use environment variables (%env(WURFL_API_KEY)%) in acf_wurfl.yaml.
   • Example:

     wurfl:
         api_key: '%env(WURFL_API_KEY)%'
     

2. Rate Limiting

   • WURFL APIs often have rate limits. Cache responses aggressively (e.g., 24h TTL for static user agents).
   • Monitor API calls in monolog logs for unexpected spikes.

3. User-Agent Parsing

   • Malformed or empty User-Agent strings can break detection. Validate input:

     $userAgent = $request->headers->get('User-Agent', '');
     if (empty($userAgent)) {
         throw new \RuntimeException('User-Agent header missing');
     }
     

4. Bundle Compatibility

   • The bundle assumes Symfony 5+. Test thoroughly if using older versions.
   • Conflicts may arise with other bundles modifying the User-Agent header (e.g., proxy bundles).

5. Capability Names

   • WURFL capability names are case-sensitive (e.g., is_tablet vs Is_Tablet). Refer to the WURFL Capabilities List for exact names.

Debugging Tips

1. Enable Verbose Logging Add to config/packages/acf_wurfl.yaml:

   wurfl:
       debug: true
   

   Logs will include raw WURFL responses and errors.

2. Test with Known User Agents Use hardcoded user agents for debugging:

   $deviceInfo = $this->wurfl->getDeviceInfo('Mozilla/5.0 (Linux; Android 10; SM-A505FN) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.149 Mobile Safari/537.36');
   

3. Check HTTP Status Codes WURFL API errors (e.g., 401 Unauthorized) may not bubble up. Wrap calls:

   try {
       $deviceInfo = $this->wurfl->getDeviceInfo($userAgent);
   } catch (\Exception $e) {
       $this->logger->error('WURFL API error: ' . $e->getMessage());
       // Fallback logic
   }
   

Extension Points

1. Custom Capability Mappings Override capability names in config:

   wurfl:
       custom_capabilities:
           is_mobile: is_mobile_browser
           device_brand: brand_name
   

2. Event Listeners Extend the bundle by subscribing to its events (if supported). Example:

   // In a service
   $eventDispatcher->addListener(AcfWurflEvents::DEVICE_DETECTED, function (DeviceDetectedEvent $event) {
       $event->setData('custom_field', 'value');
   });
   

3. Database Storage Store WURFL responses in a database for offline use:

   $this->wurfl->saveDeviceInfo($userAgent, $deviceInfo);
   $storedInfo = $this->wurfl->getStoredDeviceInfo($userAgent);
   

4. Fallback Strategies Implement fallback logic for offline modes:

   if (!$this->wurfl->isOnline()) {
       return $this->wurfl->getFallbackDeviceInfo($userAgent);
   }