Mobile-Detect: PHP user-agent detection with a rolling branch per major version

Three branches, three namespaces, three different jobs

The README's support matrix is the single most useful thing in this repository, and it is worth reading before installing anything. Three major lines run in parallel, each on its own rolling branch, with tags following a `<major>.<minor>.<patch>` pattern that always live on the matching branch. The 2.x line sits in the legacy `\Mobile_Detect` namespace, supports PHP 5.6 and above but below 7.0, and is marked Deprecated. The 3.x line uses the `Detection\MobileDetect` namespace, supports PHP 7.4 up to but not including 8.0, and is labelled LTS. The 4.x line shares the `Detection\MobileDetect` namespace, requires PHP 8.2 as of 4.10.0 where it previously required 8.0, and is the one the README marks as current and recommended.

So there is a real decision here rather than a default. A project that must keep running on PHP 7.4 has a maintained answer in 3.x. A project on a current PHP 8 should take 4.x. A project stuck on the old namespace and old runtime is on a deprecated branch, and the README says so without softening it. That candour is unusual and it saves you from discovering the situation during a PHP upgrade eighteen months from now.

The 3.x and 4.x lines share a namespace but not a runtime floor, which means code written against one may assume behaviour the other does not have. The 4.9.0 release notes are specific about this kind of tightening: PHP 8.4 compatibility work adding explicit type hints where the engine now requires them, and dropping PHP 8.0 and 8.1 from the CI matrix. Those are the changes that break upgrades quietly.

The default branch is 4.x, so a fresh clone gets the current line rather than the deprecated one.

Detection is a user-agent read plus a handful of HTTP headers

The description is more precise than the name suggests. MobileDetect is a lightweight PHP class that combines the user-agent string with specific HTTP headers to detect the mobile environment, and it covers tablets rather than treating them as a separate problem. That header part matters more than it first appears, because user-agent alone is a weak signal on its own while the combination is considerably stronger.

The class exposes the usual predicates that you would expect from a library with this history: whether the current request is a mobile request, a tablet request, and per-platform and per-device queries on top of that. The tiered structure is what allows a caller to ask progressively narrower questions, checking mobile first and only then asking which mobile, so a cheap test short-circuits an expensive one. The 4.x release notes also show the maintainer keeping the detection tables current, adding a broad Lenovo TB prefix match for modern tablets and 2025 Samsung tablet models including Tab S11, S10 Lite and A11.

Those specific entries are the argument for using a maintained library rather than a regex. Device tables are maintenance work with no ceiling, and a library whose release history shows individual tablet models being added by hand is a library that is still doing that work. The alternative, a hand-written match on the user-agent in your own code, gets stale the moment a manufacturer ships something new and nobody notices for a year.

The files this repository ships that most libraries do not

The tree is where this project distinguishes itself from its competitors. Beyond the expected README, LICENSE and tests, there are five documentation files that tell you what kind of maintainer is running this. `KNOWN_LIMITATIONS.md` is the standout. A detection library that publishes where its heuristic fails is making a different claim from one that promises correct answers, and this one makes the honest claim. `PERFORMANCE.md` does the same for speed. `RESEARCH.md` suggests the detection tables are built from cited sources rather than from whatever matched last.

Then there is the development tooling, which is unusually complete for a single-class library. `phpbench.json` configures a benchmark harness, `.php-cs-fixer.php` and `.phpcs.xml` pin code style, and a `docker-compose.yml` defines named services that run the whole verification set in containers. Each service targets one thing:

runQualityCheck:
    image: php:8.4-alpine
    command: >
      /bin/sh -c "vendor/bin/phpstan analyse --debug --memory-limit=1G --level 3 src tests"

There are parallel services for unit tests with xdebug coverage, for the benchmark suite, for linting via phpcs and phpcbf, and for the quality check above, plus a pre-release gate that runs all of them. The README's own testing command matches the compose service:

vendor/bin/phpunit -v -c tests/phpunit.xml --coverage-html .coverage

A repository that ships its own reproducible container definitions for the test, performance, lint and quality suites is making a different promise from one that says run composer test. It also means a contributor without PHP 8.4 installed locally can still run the full check set, which is a real onboarding benefit rather than a philosophical one.

The 4.11.0 release is a single change, described as an overhaul of the benchmark suite with advisory CI and release hygiene. That is an unusual thing to release for, and a useful signal: it means the performance numbers the project publishes are backed by tooling that gets maintained.

Where user-agent detection fails, and what to do about it

The honest limitation is structural rather than a bug that a release will fix. A user-agent string is supplied by the client, and any client can supply any string. That is true of every user-agent detection library ever written, and the fix will never be a better matching table.

The realistic uses are layout and capability decisions. Show a simplified layout on a narrow viewport, request a smaller image variant, avoid a hover-dependent interaction. Those degrade gracefully when the detection is wrong. The uses to avoid are anything with a security consequence: gating a feature behind a device check, deciding an authentication flow, or inferring a device's capability to satisfy an access control. Client-controlled input cannot support those decisions, no matter how many device models the tables contain.

Client-side hints are the direction the platform has moved, with browsers offering structured hints about viewport, device pixel ratio and platform instead of asking the server to parse a string. That is a better mechanism, and PHP cannot fully benefit from it because the hints arrive as headers only on subsequent requests. It is worth knowing that the trajectory of the underlying problem is away from what this library does well, and that a feature-detecting approach on the client handles more real devices than any table.

Where you do need server-side classification, such as deciding whether to render a simplified transactional email, the combination of user-agent and headers that this library implements is a reasonable approximation. Just keep the consequence of being wrong small.

Editorial conclusion

Mobile-Detect is the safest answer to device detection in PHP, and the reason is not the matching tables but the discipline around them. A named support matrix, a rolling branch per major line, a benchmark harness and a limitations file that documents where the heuristic fails are exactly what a detection library should ship and rarely does. Start on the 4.x branch, which the README marks as current and recommended, and remember that the library identifies a class of hardware from a header it does not control. Treat the result as a hint for choosing a layout, never as an authentication or authorisation input.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. serbanghita/Mobile-Detect on GitHub