Download the PHP package atldays/laravel-agent without Composer

Laravel Agent

atldays/laravel-agent is a Laravel package for parsing user-agent strings into clean, typed objects.

It gives you a comfortable Laravel-first API for working with:

• browsers
• operating systems
• devices
• bots
• request user-agent strings

Under the hood, the package uses matomo/device-detector, while exposing a clean developer experience through Laravel service container bindings, a request macro, facades, model helpers, and typed DTOs powered by spatie/laravel-data.

Features

• Laravel auto-discovery support
• request()->agent() request macro
• Agent facade for the current request agent
• AgentManager facade for on-demand detection
• dependency injection support via AgentContract
• container binding for AgentContract
• typed DTO objects for browser, OS, device, bot, and producer data
• Eloquent cast for persisted user-agent strings
• model trait for convenient access to parsed agents
• bot-blocking middleware alias
• test coverage for real user-agent fixtures and framework integration

Requirements

• PHP ^8.2
• Laravel ^11.0|^12.0|^13.0

Installation

The package supports Laravel package auto-discovery, so no manual provider registration is required.

Quick Start

Request macro

Facades

Dependency injection

Core API

The main parsed object is Atldays\Agent\Contracts\AgentContract.

Available methods:

• userAgent(): string
• hash(): string
• browser(): ?BrowserContract
• os(): ?OsContract
• device(): ?DeviceContract
• bot(): ?BotContract
• isBot(): bool
• toArray(): array

Example:

DTO Objects

The package returns typed DTO objects instead of raw arrays.

Browser DTO

Returned by:

• $agent->browser()

Class:

• Atldays\Agent\Data\Browser

Available data methods:

• name(): string
• shortName(): ?string
• version(): ?string
• family(): ?string
• engine(): ?string
• engineVersion(): ?string

Available helper methods:

• isChrome(): bool
• isEdge(): bool
• isFirefox(): bool
• isOpera(): bool
• isSafari(): bool

Example:

OS DTO

Returned by:

• $agent->os()

Class:

• Atldays\Agent\Data\Os

Available data methods:

• name(): string
• shortName(): ?string
• version(): ?string
• family(): ?string
• platform(): ?string

Available helper methods:

• isApple(): bool
• isAndroid(): bool
• isIos(): bool
• isLinux(): bool
• isMacOs(): bool
• isWindows(): bool

Example:

Device DTO

Returned by:

• $agent->device()

Class:

• Atldays\Agent\Data\Device

Available data methods:

• type(): DeviceType
• device(): string
• brand(): ?string
• model(): ?string

Available helper methods:

• isDesktop(): bool
• isMobile(): bool
• isTablet(): bool
• isPhone(): bool
• isApple(): bool
• isIphone(): bool

Example:

Bot DTO

Returned by:

• $agent->bot()

Class:

• Atldays\Agent\Data\Bot

Available data methods:

• name(): string
• category(): ?string
• url(): ?\Atldays\Url\Contracts\Url
• producer(): ?ProducerContract

Producer DTO

Returned by:

• $agent->bot()?->producer()

Class:

• Atldays\Agent\Data\Producer

Available data methods:

• name(): ?string
• url(): ?\Atldays\Url\Contracts\Url

Manual Detection

If you already have a user-agent string, you can parse it directly:

You can also resolve the manager directly:

Eloquent Integration

Agent cast

Use AgentCast when your model stores a raw user_agent string but you want to work with an AgentContract.

Now the attribute will resolve to an AgentContract:

HasAgent trait

Use the trait when you want a dedicated agent() helper on your model.

Example:

By default the trait reads from the user_agent column. You can override that:

Middleware

The package registers the agent.block-bots middleware alias.

Block all bots

Allow selected bots

If a request is detected as a bot and is not allow-listed, the middleware throws a 403 Forbidden response.

Testing

Run the test suite:

Run formatting:

Run both:

Why Laravel Agent

Most user-agent packages stop at “parse a string into an array”.

laravel-agent is built to feel native inside a Laravel application:

• typed objects instead of loose arrays
• request-first API for day-to-day usage
• model integration for persisted user agents
• framework-friendly container bindings and facade support
• focused helper methods on DTOs for browser, OS, and device checks

License

The MIT License (MIT). Please see LICENSE.md for more information.