Phpuseragentparser Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require donatj/phpuseragentparser
   

2. Basic Usage (procedural):

   use donatj\UserAgent\parse_user_agent;
   
   $userAgent = $_SERVER['HTTP_USER_AGENT'] ?? '';
   $parsed = parse_user_agent($userAgent);
   
   echo $parsed['platform']; // e.g., "Macintosh"
   echo $parsed['browser'];  // e.g., "Chrome"
   

3. Basic Usage (object-oriented):

   use donatj\UserAgent\UserAgentParser;
   
   $parser = new UserAgentParser();
   $ua = $parser->parse($_SERVER['HTTP_USER_AGENT'] ?? '');
   
   echo $ua->platform();       // e.g., "Macintosh"
   echo $ua->browser();        // e.g., "Chrome"
   echo $ua->browserVersion(); // e.g., "120.0.0"
   

First Use Case

Detect mobile vs. desktop traffic in a Laravel middleware:

use donatj\UserAgent\UserAgentParser;

public function handle($request, Closure $next)
{
    $parser = new UserAgentParser();
    $ua = $parser->parse($request->userAgent());

    if ($ua->isMobile()) {
        // Redirect or serve mobile-specific content
    }

    return $next($request);
}

Implementation Patterns

Common Workflows

1. Request-Based Parsing

Parse user agents from incoming requests (e.g., in controllers, middleware, or services):

public function show(Request $request)
{
    $parser = new UserAgentParser();
    $ua = $parser->parse($request->userAgent());

    if ($ua->isBot()) {
        return response()->json(['message' => 'Bot detected'], 403);
    }

    return view('home', ['browser' => $ua->browser()]);
}

2. Conditional Logic

Use parsed data for feature flags or A/B testing:

if ($ua->browser() === 'Safari' && $ua->platform() === 'iPhone') {
    // Enable iOS-specific features
}

3. Caching Parsed Results

Avoid reprocessing the same user agent string repeatedly (e.g., in a service layer):

class UserAgentService
{
    protected $cache = [];

    public function parse(string $userAgent): UserAgent
    {
        if (!isset($this->cache[$userAgent])) {
            $this->cache[$userAgent] = (new UserAgentParser())->parse($userAgent);
        }
        return $this->cache[$userAgent];
    }
}

4. Integration with Laravel Requests

Extend the Request class or use a trait to add parsing methods:

trait UserAgentParsing
{
    public function userAgentParser(): UserAgentParser
    {
        return new UserAgentParser();
    }

    public function isMobile(): bool
    {
        return $this->userAgentParser()->parse($this->userAgent())->isMobile();
    }
}

5. Logging and Analytics

Log parsed user agent data for analytics:

$logger->info('User Agent', [
    'platform' => $ua->platform(),
    'browser' => $ua->browser(),
    'version' => $ua->browserVersion(),
    'is_bot' => $ua->isBot(),
]);

Integration Tips

Laravel Service Providers

Register the parser as a singleton in AppServiceProvider:

public function register()
{
    $this->app->singleton(UserAgentParser::class, function () {
        return new UserAgentParser();
    });
}

Dependency Injection

Inject the parser into controllers or services:

use donatj\UserAgent\UserAgentParser;

class AnalyticsController
{
    public function __construct(protected UserAgentParser $parser) {}

    public function index()
    {
        $ua = $this->parser->parse(request()->userAgent());
        // ...
    }
}

Middleware for Bot Detection

Create middleware to block or redirect bots:

public function handle($request, Closure $next)
{
    $ua = (new UserAgentParser())->parse($request->userAgent());

    if ($ua->isBot()) {
        return response()->json(['error' => 'Access denied'], 403);
    }

    return $next($request);
}

Custom User Agent Parsing

Extend the parser for project-specific needs (e.g., legacy browser support):

class CustomUserAgentParser extends UserAgentParser
{
    public function isLegacyBrowser(): bool
    {
        $browser = $this->parse($this->userAgent)->browser();
        return in_array($browser, ['MSIE', 'Firefox', 'Safari']);
    }
}

Gotchas and Tips

Pitfalls

1. Brave Browser Detection

• Issue: Brave cannot be distinguished from Chrome.
• Workaround: Assume Chrome if the user agent suggests Brave.
• Tip: Log undetected cases for manual review:

  if ($ua->browser() === 'Chrome' && str_contains($userAgent, 'Brave')) {
      logger()->warning('Brave detected as Chrome', ['user_agent' => $userAgent]);
  }
  

2. iPadOS Detection

• Issue: iPadOS 13+ returns the same user agent as macOS.
• Workaround: Use JavaScript-based detection or rely on other signals (e.g., touch events).
• Tip: Document limitations in your code:

  // iPadOS 13+ cannot be distinguished from macOS
  if ($ua->platform() === 'Macintosh' && str_contains($userAgent, 'iPad')) {
      logger()->info('Potential iPadOS 13+ detected as macOS');
  }
  

3. OS Version Limitations

• Issue: User agent strings are unreliable for OS version detection.
• Workaround: Avoid relying on OS versions; use feature detection or server-side logic instead.
• Tip: Add a comment to clarify:

  // Note: OS version detection is unreliable; avoid using this for critical logic.
  $osVersion = $ua->osVersion(); // May return null or inaccurate data
  

4. Deprecated Global Function

• Issue: parse_user_agent() is deprecated in favor of \donatj\UserAgent\parse_user_agent().
• Fix: Update all usages to the namespaced version:

  // Old (deprecated)
  $ua = parse_user_agent($userAgent);
  
  // New
  $ua = \donatj\UserAgent\parse_user_agent($userAgent);
  

5. Case Sensitivity

• Issue: Some browser names (e.g., "Edge") are case-sensitive.
• Tip: Always use constants from donatj\UserAgent\Browsers for comparisons:

  if ($ua->browser() === \donatj\UserAgent\Browsers::EDGE) {
      // Correct
  }
  

Debugging Tips

1. Log Raw User Agent Strings

Debug undetected user agents by logging raw strings:

logger()->debug('Undetected User Agent', [
    'raw' => $userAgent,
    'parsed' => $ua->toArray(),
]);

2. Test Edge Cases

Test with known problematic user agents:

$testCases = [
    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36 Edg/120.0.0.0',
    'Mozilla/5.0 (iPad; CPU OS 13_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/120.0.0.0 Mobile/15E148 Safari/605.1',
];

foreach ($testCases as $uaString) {
    $ua = (new UserAgentParser())->parse($uaString);
    logger()->info('Test Result', ['user_agent' => $uaString, 'parsed' => $ua->toArray()]);
}

3. Check for Updates

The package is actively maintained; check for new releases:

composer show donatj/phpuseragentparser

Extension Points

1. Custom Platforms/Browsers

Extend the parser by adding new regex patterns or constants:

// Add a custom platform (e.g., "CustomOS")
\donatj\UserAgent\Platforms::add('CustomOS', '/Custom