arraypress / wp-user-agent-utils
A lean WordPress utility for browser detection, device recognition, and bot identification
Requires
- php: >=8.3
Requires (Dev)
- phpcompatibility/phpcompatibility-wp: ^2.1
- phpunit/phpunit: ^12.0
- squizlabs/php_codesniffer: ^3.13.5
- wp-coding-standards/wpcs: ^3.4
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
This library has moved. It is now part of
sugarcommerce/network(namespaceSugarCommerce\Network, PHP 8.3+). That package's README has a "Moving from arraypress/wp-*" table. This repository is archived and read-only.
WordPress User Agent Utilities
Work out what is making the request — including which AI crawler.
What it does
The user agent string is the only thing a request tells you about the client, and parsing it is tedious and easy to get wrong. Most libraries that do it are enormous, because they try to identify every browser version ever shipped.
This answers the questions a plugin actually asks: is this a phone, is this a bot, and — increasingly — is this an AI crawler you might want to treat differently from Googlebot.
The rules and the lists are the ones the JavaScript package
@flarecart/user-agent uses, so
the same string gets the same answer on both sides.
Features
- Tell mobile, tablet and desktop apart
- Identify bots, and AI crawlers specifically — and an AI crawler from an AI fetching a page because a person asked for it
- Name the app whose in-app browser this is (TikTok, Instagram, Facebook), which is usually the only clue to where a social visitor came from
- Spot a link preview (WhatsApp, Slack, Discord, iMessage), so a pasted link is not counted as a visit or a download
- Name a command-line tool or HTTP library: curl, Python, Go
- Name Brave and Edge, and tell Windows 11 from 10, from client hints
- Get a readable description of the client for a log or an order record
- Read the raw agent safely, unslashed and sanitised
Installation
composer require arraypress/wp-user-agent-utils
Quick start
use ArrayPress\UserAgentUtils\Request; // Record what the order was placed from. update_post_meta( $order_id, '_device', Request::device_type() ); // Do not count AI crawlers as visitors. if ( Request::is_ai_bot() ) { return; } // Nor a chat app drawing the card for a pasted link. if ( Request::is_link_preview() ) { return; } // A readable line for the log: "Chrome 131 on macOS", // "Instagram in-app browser on iOS", "WhatsApp link preview", "curl". $log->info( 'Checkout started', [ 'client' => Request::describe() ] ); // "TikTok", when the visitor is in TikTok's own browser and sent no referrer. $app = Request::in_app_browser();
Everything about an agent string at once, with nothing read from the request:
use ArrayPress\UserAgentUtils\UserAgent; UserAgent::parse( $agent ); // [ 'browser' => 'iOS WebView', 'version' => null, 'os' => 'iOS', // 'device' => 'mobile', 'bot' => false, 'in_app' => 'TikTok', // 'label' => 'TikTok in-app browser on iOS', ... ]
Browsers are named as browsers, not devices: Chrome on a phone is Chrome,
and device says it is a phone.
Requirements
- PHP 8.3 or later
- WordPress 7.1 or later
License
GPL-2.0-or-later