CLAUDE.md

Whenever you find a new rule that applies to this project, add it to this file.

Project

PHP library (Detection\MobileDetect) for detecting mobile devices/tablets via User-Agent strings and HTTP headers. Requires PHP >= 8.0. PSR-12 code style.

Branch & Release

• Active branch: 4.x (rolling — one branch per major). Always rebase into 4.x (not main or master). Tags follow <major>.<minor>.<patch>.
• On new tag: update @version docblock + $VERSION property in src/MobileDetect.php, and version in MobileDetect.json.

Commands

# Tests
vendor/bin/phpunit -v -c tests/phpunit.xml
vendor/bin/phpunit -v -c tests/phpunit.xml --filter testMethodName

# Lint + static analysis
vendor/bin/phpcs
vendor/bin/php-cs-fixer fix
vendor/bin/phpstan analyse --memory-limit=1G --level 3 src tests

# Benchmark (defaults live in /phpbench.json and per-method @Revs/@Iterations)
composer bench                # aggregate report
composer bench:baseline       # stores tag=baseline + phpbench-baseline.xml
composer bench:compare        # runs with --ref=baseline, enforces 2% @Assert
# Advisory CI: .github/workflows/4.x-bench.yml runs on every PR to 4.x,
# uploads artifacts, and posts a PR comment. Does not block merge.

Performance reviews

Every time you run a performance review (ad-hoc benchmarking, before a release, after touching a hot path, or at the end of a perf-oriented PR), append a new dated section to PERFORMANCE.md using the template block at the bottom of that file. Do not edit prior sections — they are a historical record for regression comparison.

Minimum contents per section: branch/commit, PHP image, host, phpbench config, the full aggregate table (13 subjects today), and a short notes list interpreting what's surprising or actionable in the numbers.

Architecture

src/
  MobileDetect.php          # Core class: regex patterns, isMobile(), isTablet(), is(), version(), magic isXXXX() via __call
  MobileDetectStandalone.php # Non-Composer wrapper (loads standalone/ autoloader)
  Cache/Cache.php            # In-memory PSR-16 cache with TTL
  Exception/                 # MobileDetectException + error codes
tests/
  providers/vendors/*.php    # UA fixture arrays per vendor (Apple, Samsung, etc.)
  UserAgentTest.php          # Data-driven tests from vendor fixtures
  MobileDetectGeneralTest.php # Core logic tests
  CacheTest.php, MobileDetectWithCacheTest.php, MobileDetectExceptionTest.php
  Benchmark/MobileDetectBench.php   # PHPBench suite (PSR-4: DetectionTests\Benchmark)

Key Patterns

• Detection results are cached via PSR-16 (CacheInterface). Default: in-memory Cache. Cache keys use sha1 by default.
• $_SERVER HTTP headers auto-initialized unless autoInitOfHttpHeaders config is false.
• CloudFront headers (HTTP_CLOUDFRONT_IS_MOBILE_VIEWER, etc.) are recognized for AWS detection.
• Magic isXXXX() calls dispatch through __call -> is() -> match() against static regex arrays ($phoneDevices, $tabletDevices, $operatingSystems, $browsers).