Laravel Http User Agent Laravel Package

Getting Started

• Install with composer require vendor/package; the service provider is auto-discovered on Laravel 5.5+.
• Publish the config first: php artisan vendor:publish --tag=package-config. That file is the source of truth for the options the middleware will apply — read it before reading the code.
• Read the 1.1.0 changelog entry before upgrading. The globalOptions() method is gone in favour of middleware. If your app (or a wrapper package) calls globalOptions() directly, that call is now dead code at best and a fatal error at worst.
• Register the middleware. Laravel 11/12 (bootstrap/app.php):

  ->withMiddleware(function (Middleware $middleware) {
      $middleware->append(\Vendor\Package\Middleware\ApplyGlobalOptions::class);
  })
  

  Laravel 10 and below: add the class to $middleware (global) or $middlewareGroups['web'] in app/Http/Kernel.php.
• First use case: apply one consistent set of options across every HTTP request so controllers and form requests stop repeating the same setup. Register the middleware globally, hit any route, and confirm it ran by dumping in handle() or asserting on the resulting response.

Implementation Patterns

• Global vs. group-scoped. Append to the global stack when the options genuinely apply everywhere; put it in the web group when API routes must stay untouched. The middleware approach makes this decision explicit, which is the main win over the old implicit globalOptions() call.
• Ordering matters. The middleware only sets options for whatever runs after it. Register it before anything that reads those options (auth, localization, response decorators). On Laravel 11+ use $middleware->priority([...]) if auto-ordering puts it in the wrong place.
• Config-driven, environment-aware. Keep option values in config/package.php and vary them per environment via .env. The middleware reads config at request time, so config:cache in production is fine — just remember to rebuild it on deploy.
• Per-route opt-out. Exempt health checks, webhooks and asset routes with ->withoutMiddleware(ApplyGlobalOptions::class) on the route or group rather than branching inside handle().
• Testing. Use $this->withMiddleware() to include it in feature tests and assert on the observable effect (headers, resolved options) rather than on the middleware class itself. Use $this->withoutMiddleware() only for tests that are unrelated to option resolution.
• Custom behaviour. Extend the middleware and rebind it in a service provider ($this->app->bind(...)) or use $middleware->replace() on Laravel 11+ instead of forking the package.
• Console/queue parity. If non-HTTP code also needs these options, extract the resolution into a small action or service class and call it from both the middleware and your jobs/commands.

Gotchas and Tips

• 1.1.0 is effectively a breaking change. Anything calling globalOptions() must be removed. Grep for globalOptions across app/, your own packages and any published vendor overrides before deploying.
• Middleware only runs on HTTP requests. If the old globalOptions() call happened in a service provider, it also affected console commands, queued jobs and scheduled tasks. Those contexts silently lose the behaviour after upgrading. This is the most likely production surprise — audit non-HTTP entry points.
• Silent no-ops in tests. withoutMiddleware() in a base test case will disable the new middleware everywhere and your assertions will pass for the wrong reason. Assert the effect at least once with middleware enabled.
• Stale caches. After upgrading run php artisan optimize:clear; route caching and config caching both hide middleware registration changes and produce confusing "it works in tinker but not in the browser" symptoms.
• Verify registration with php artisan route:list -v (shows middleware per route) or Telescope's request detail panel, rather than guessing from behaviour.
• Octane / long-running workers. Config is read per request here, so it is safe, but any static caching you add inside a custom subclass will leak between requests — resolve from config() in handle(), not in the constructor.
• Extension points. The middleware class, the config file and the container binding are the three supported seams. Prefer binding a subclass over editing vendor files so the next patch release stays applyable.