CrawlerDetect

https://github.com/jaybizzle/crawler-detect
Admin
CrawlerDetect is a PHP library for detecting bots, crawlers, and spiders via User-Agent and...
Tokens:21,911
Snippets:299
Trust Score:9.9
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install via Composer

Source: https://github.com/jaybizzle/crawler-detect/blob/master/README.md

Install the CrawlerDetect library using Composer.

```bash
composer require jaybizzle/crawler-detect
```

--------------------------------

### Get all header names

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/Fixtures/Headers.md

Instantiates Headers and calls getAll() to retrieve the list. The first entry is 'HTTP_USER_AGENT' and the ninth is 'HTTP_FROM'.

```php
use Jaybizzle\CrawlerDetect\Fixtures\Headers;

$names = (new Headers)->getAll();
var_dump($names[0]); // 'HTTP_USER_AGENT'
var_dump($names[8]); // 'HTTP_FROM'
```

--------------------------------

### Usage example: listing signatures and checking a UA

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/Fixtures/Crawlers.md

Demonstrates retrieving patterns via getAll() and using isCrawler() to test a user agent string.

```php
use Jaybizzle\CrawlerDetect\Fixtures\Crawlers;
use Jaybizzle\CrawlerDetect\CrawlerDetect;

// List a few signatures
$patterns = (new Crawlers)->getAll();
var_dump($patterns[0], $patterns[1472]); // ' YLT', '[a-z0-9\-_]*(bot|...|scraper)'
```

```php
$cd = new CrawlerDetect;
var_dump($cd->isCrawler('Mozilla/5.0 (compatible; bingbot/2.0; +http://www.bing.com/bingbot.htm)')); // true
```

--------------------------------

### compileRegex usage example

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Creates a CrawlerDetect instance and compiles the Exclusions fixture patterns into a single regex string. The comment shows the expected joined result, e.g. '(?:Safari\/[\d\.]*|Firefox\/[\d\.]*|...)'.

```php
use Jaybizzle\CrawlerDetect\CrawlerDetect;
use Jaybizzle\CrawlerDetect\Fixtures\Exclusions;

$cd = new CrawlerDetect;
$joined = $cd->compileRegex((new Exclusions)->getAll());

// $joined === '(?:Safari\/[\d\.]*|Firefox\/[\d\.]*|...)'
```

--------------------------------

### Example crawler patterns from the dataset

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/Fixtures/Crawlers.md

Shows several recurring pattern shapes used in the crawler signatures, including anchored and full-match patterns.

```php
'^Aether',
'^Amazon Simple Notification Service Agent$',
'^Dart\/[0-9]',
'^Java\/',
'Mozilla\/5\.0 (compatible; Googlebot\/2\.1; \+http:\/\/www\.google\.com\/bot\.html)',
'bingbot\/2\.0',
```

--------------------------------

### getUaHttpHeaders iteration example

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Iterates over the user-agent headers returned by getUaHttpHeaders, printing each header name like 'HTTP_USER_AGENT' or 'HTTP_FROM'.

```php
$cd = new CrawlerDetect;

foreach ($cd->getUaHttpHeaders() as $header) {
    // 'HTTP_USER_AGENT', 'HTTP_FROM', ...
}
```

--------------------------------

### getMatches() usage example

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Shows how to retrieve the matched text after a successful isCrawler() call. The output is e.g. "Matched: monitoring" for Yahoo Ad monitoring.

```php
$CrawlerDetect = new CrawlerDetect;

if ($CrawlerDetect->isCrawler()) {
    echo 'Matched: '.$CrawlerDetect->getMatches();
    // e.g. "Matched: monitoring" for Yahoo Ad monitoring
}
```

--------------------------------

### CrawlerDetect class usage and methods

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/index.md

Shows the entry point class with constructor variants and all public methods. The constructor reads $_SERVER by default, or accepts an explicit header map and user agent. Methods return bool, string|null, or array as documented.

```php
use Jaybizzle\CrawlerDetect\CrawlerDetect;

$CrawlerDetect = new CrawlerDetect;                 // reads $_SERVER by default
$CrawlerDetect = new CrawlerDetect($headers);       // explicit header map
$CrawlerDetect = new CrawlerDetect($headers, $ua);  // explicit header map + user agent

$CrawlerDetect->isCrawler();                   // bool — check the current/stored agent
$CrawlerDetect->isCrawler('SomeBot/1.0');      // bool — check an explicit string
$CrawlerDetect->getMatches();                  // string|null — matched text
$CrawlerDetect->getUserAgent();                // string|null — stored agent
$CrawlerDetect->getUaHttpHeaders();            // array — the 11 header names consulted
$CrawlerDetect->setHttpHeaders($headers);      // void — replace the header map
$CrawlerDetect->setUserAgent($ua);             // string|null — replace the stored agent
$CrawlerDetect->compileRegex($patterns);       // string — join patterns into one regex
```

--------------------------------

### Import AbstractProvider

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/Fixtures/AbstractProvider.md

Import path for the AbstractProvider class.

```php
use Jaybizzle\CrawlerDetect\Fixtures\AbstractProvider;
```

--------------------------------

### Using Crawlers fixture with getAll

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/Fixtures/AbstractProvider.md

Instantiates the Crawlers fixture and retrieves its patterns via getAll(), then prints the count.

```php
use Jaybizzle\CrawlerDetect\Fixtures\Crawlers;

$crawlers = new Crawlers;
$patterns = $crawlers->getAll();

printf('%d crawler patterns loaded', count($patterns));
```

--------------------------------

### getAll method signature

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/Fixtures/AbstractProvider.md

Public method that returns the fixture's data array. No parameters; returns an array.

```php
/**
 * Return the data set.
 *
 * @return array
 */
public function getAll()
```

--------------------------------

### new CrawlerDetect($headers, $userAgent)

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/index.md

Constructor for the CrawlerDetect class. Reads $_SERVER by default, or accepts an explicit header map and user agent string.

```APIDOC
## Constructor: new CrawlerDetect($headers, $userAgent)

### Description
Creates a new CrawlerDetect instance. Reads $_SERVER by default, or accepts an explicit header map and user agent string.

### Parameters
- **$headers** (?array) - Optional - Header map (e.g., $_SERVER, PSR-7, Symfony HeaderBag, Swoole, Lambda events)
- **$userAgent** (string) - Optional - User agent string

### Request Example
```php
use Jaybizzle\CrawlerDetect\CrawlerDetect;

$CrawlerDetect = new CrawlerDetect;                 // reads $_SERVER by default
$CrawlerDetect = new CrawlerDetect($headers);       // explicit header map
$CrawlerDetect = new CrawlerDetect($headers, $ua);  // explicit header map + user agent
```

### Response
#### Success Response
Returns a new CrawlerDetect instance.
```

--------------------------------

### Processing any fixture uniformly with AbstractProvider

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/Fixtures/AbstractProvider.md

Uses the abstract type to accept any fixture and call getAll() uniformly. Shows expected output counts for each concrete fixture.

```php
use Jaybizzle\CrawlerDetect\Fixtures\AbstractProvider;
use Jaybizzle\CrawlerDetect\Fixtures\Crawlers;
use Jaybizzle\CrawlerDetect\Fixtures\Exclusions;
use Jaybizzle\CrawlerDetect\Fixtures\Headers;

function describe(AbstractProvider $fixture): string
{
    return get_class($fixture).': '.count($fixture->getAll()).' entries';
}

echo describe(new Crawlers);   // Jaybizzle\CrawlerDetect\Fixtures\Crawlers: 1473 entries
echo describe(new Exclusions); // Jaybizzle\CrawlerDetect\Fixtures\Exclusions: 52 entries
echo describe(new Headers);    // Jaybizzle\CrawlerDetect\Fixtures\Headers: 11 entries
```

--------------------------------

### Catch-all suffix pattern for bot-like UAs

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/Fixtures/Crawlers.md

Final entry in the dataset that matches any UA containing bot-related words; enables detection of strings like 'somenaughtybot'.

```php
'[a-z0-9\-_]*(bot|crawl|headless|archiver|transcoder|spider|uptime|validator|fetcher|cron|checker|reader|extractor|monitoring|analyzer|scraper)',
```

--------------------------------

### Import Headers class

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/Fixtures/Headers.md

Imports the Headers class for use in other PHP files.

```php
use Jaybizzle\CrawlerDetect\Fixtures\Headers;
```

--------------------------------

### Import path for CrawlerDetect

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Shows how to import the CrawlerDetect class using its fully qualified namespace.

```php
use Jaybizzle\CrawlerDetect\CrawlerDetect;
```

--------------------------------

### Constructor signature for CrawlerDetect

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Defines the constructor with optional headers and user agent parameters. Accepts SAPI-style or real header names; null falls back to $_SERVER.

```php
/**
 * Class constructor.
 */
public function __construct(?array $headers = null, $userAgent = null)
```

--------------------------------

### Basic usage with isCrawler and getMatches

Source: https://github.com/jaybizzle/crawler-detect/blob/master/README.md

Instantiate CrawlerDetect, check the current visitor's user agent, pass a custom user agent string, and output the matched part.

```php
use Jaybizzle\CrawlerDetect\CrawlerDetect;

$CrawlerDetect = new CrawlerDetect;

// Check the user agent of the current visitor
if ($CrawlerDetect->isCrawler()) {
    // true if a crawler user agent was detected
}

// Pass a user agent as a string
if ($CrawlerDetect->isCrawler('Mozilla/5.0 (compatible; Sosospider/2.0; +http://help.soso.com/webspider.htm)')) {
    // true if a crawler user agent was detected
}

// Output the part of the user agent that matched (if any)
echo $CrawlerDetect->getMatches();
```

--------------------------------

### getMatches()

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/index.md

Returns the matched text from the crawler detection, or null if no match.

```APIDOC
## Method: getMatches()

### Description
Returns the matched text from the crawler detection, or null if no match.

### Request Example
```php
$CrawlerDetect->getMatches();                  // string|null — matched text
```

### Response
#### Success Response
- **string|null** - The matched text, or null if no match
```

--------------------------------

### setUserAgent($ua)

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/index.md

Replaces the stored user agent string. Returns the new user agent or null.

```APIDOC
## Method: setUserAgent($ua)

### Description
Replaces the stored user agent string. Returns the new user agent or null.

### Parameters
- **$ua** (string) - Required - The new user agent string

### Request Example
```php
$CrawlerDetect->setUserAgent($ua);             // string|null — replace the stored agent
```

### Response
#### Success Response
- **string|null** - The new user agent, or null if not set
```

--------------------------------

### getUserAgent() with constructor argument

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Shows that passing an explicit agent to the constructor makes getUserAgent() return that value.

```php
$cd = new CrawlerDetect(null, 'SomeBot/1.0');

echo $cd->getUserAgent(); // 'SomeBot/1.0'
```

--------------------------------

### Import Exclusions class

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/Fixtures/Exclusions.md

Imports the Exclusions class for use in PHP code.

```php
use Jaybizzle\CrawlerDetect\Fixtures\Exclusions;
```

--------------------------------

### getUserAgent() method definition

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Returns the stored user agent: the constructor argument if given, otherwise the agent composed from headers, or null if neither was available.

```php
/**
 * @return string|null
 */
public function getUserAgent()
```

--------------------------------

### compileRegex($patterns)

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/index.md

Joins an array of patterns into a single regex string. Returns the compiled regex.

```APIDOC
## Method: compileRegex($patterns)

### Description
Joins an array of patterns into a single regex string. Returns the compiled regex.

### Parameters
- **$patterns** (array) - Required - Array of regex patterns to join

### Request Example
```php
$CrawlerDetect->compileRegex($patterns);       // string — join patterns into one regex
```

### Response
#### Success Response
- **string** - The compiled regex string
```

--------------------------------

### AbstractProvider class declaration

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/Fixtures/AbstractProvider.md

Declares the abstract base class for the library's data fixtures. It provides a uniform accessor, getAll(), for the dataset.

```php
namespace Jaybizzle\CrawlerDetect\Fixtures;

abstract class AbstractProvider
```

--------------------------------

### CrawlerDetect::__construct

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/configuration.md

Constructor for the CrawlerDetect class. Accepts optional headers and user agent to configure detection behavior.

```APIDOC
## [CONSTRUCTOR] CrawlerDetect::__construct

### Description
Initializes a new CrawlerDetect instance with optional header map and user agent string.

### Method
Constructor

### Signature
`public function __construct(?array $headers = null, $userAgent = null)`

### Parameters
- **$headers** (?array) - Optional - Header map to probe. `null` or empty array falls back to `$_SERVER`.
- **$userAgent** (string|null) - Optional - Explicit user-agent string. When `null`, composed from headers.

### Request Example
```php
$crawlerDetect = new CrawlerDetect($headers, $userAgent);
```

### Response
No return value.
```

--------------------------------

### getUaHttpHeaders()

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/index.md

Returns the array of the 11 header names consulted during detection.

```APIDOC
## Method: getUaHttpHeaders()

### Description
Returns the array of the 11 header names consulted during detection.

### Request Example
```php
$CrawlerDetect->getUaHttpHeaders();            // array — the 11 header names consulted
```

### Response
#### Success Response
- **array** - The 11 header names consulted
```

--------------------------------

### Count exclusions

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/Fixtures/Exclusions.md

Outputs the number of exclusion patterns (52) using the inherited getAll() method.

```php
use Jaybizzle\CrawlerDetect\Fixtures\Exclusions;

echo count((new Exclusions)->getAll()); // 52
```

--------------------------------

### Detect Googlebot via From header

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/Fixtures/Headers.md

Shows indirect use: a request with an innocent User-Agent but a 'From' header containing 'googlebot(at)googlebot.com' is detected as a crawler.

```php
$cd = new Jaybizzle\CrawlerDetect\CrawlerDetect([
    'From'       => ['googlebot(at)googlebot.com'],
    'User-Agent' => ['Mozilla/5.0 (Macintosh; Intel Mac OS X 10_8_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/28.0.1500.71 Safari/537.36'],
]);

var_dump($cd->isCrawler()); // true — matched via HTTP_FROM
```

--------------------------------

### isCrawler with full headers and explicit string

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Shows recommended usage from the README: pass full headers to check From and Sec-CH-UA, then fall back to an explicit User-Agent string check.

```php
// Pass full headers so From / Sec-CH-UA are checked too
$CrawlerDetect = new CrawlerDetect($request->getHeaders());

if ($CrawlerDetect->isCrawler()) {
    // ...
} else {
    // Explicit string check — only one header is ever consulted
    $ua = $request->getHeaderLine('User-Agent');
    if (! $CrawlerDetect->isCrawler($ua)) {
        // genuine visitor
    }
}
```

--------------------------------

### setUserAgent composing from headers

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Constructs CrawlerDetect with From and User-Agent headers, then calls setUserAgent() with no arguments to compose the agent from those headers.

```php
$cd = new CrawlerDetect([
    'From'      => ['googlebot(at)googlebot.com'],
    'User-Agent' => ['Mozilla/5.0 (Macintosh; Intel Mac OS X 10_8_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/28.0.1500.71 Safari/537.36'],
]);

$cd->setUserAgent();      // composed from HTTP_FROM + HTTP_USER_AGENT
$cd->getUserAgent();      // 'googlebot(at)googlebot.com Mozilla/5.0 (...)'
```

--------------------------------

### getUserAgent()

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Returns the stored user agent: the constructor argument if given, otherwise the agent composed from the headers (or null if neither was available). Passing an explicit agent to isCrawler() does not change this value.

```APIDOC
## getUserAgent()

### Description
Returns the stored user agent: the constructor argument if given, otherwise the agent composed from the headers (or `null` if neither was available). Passing an explicit agent to `isCrawler()` does **not** change this value.

### Method
`getUserAgent`

### Parameters
None.

### Return Type
`string|null` — the stored user agent.

### Examples
```php
$cd = new CrawlerDetect(null, 'SomeBot/1.0');

echo $cd->getUserAgent(); // 'SomeBot/1.0'
```

```php
$cd = new CrawlerDetect(['HTTP_USER_AGENT' => 'Mozilla/5.0 (compatible; bingbot/2.0)']);

echo $cd->getUserAgent(); // 'Mozilla/5.0 (compatible; bingbot/2.0)'
```
```

--------------------------------

### Header names data array

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/Fixtures/Headers.md

The exact entries of the $data property, listing 11 SAPI-formatted header names with comments explaining their semantics.

```php
'HTTP_USER_AGENT',              // The default User-Agent string.
'HTTP_X_OPERAMINI_PHONE_UA',    // Header can occur on devices using Opera Mini.
'HTTP_X_DEVICE_USER_AGENT',     // Vodafone specific header.
'HTTP_X_ORIGINAL_USER_AGENT',
'HTTP_X_SKYFIRE_PHONE',         // Skyfire browser
'HTTP_X_BOLT_PHONE_UA',         // Bolt browser
'HTTP_DEVICE_STOCK_UA',
'HTTP_X_UCBROWSER_DEVICE_UA',   // UC Browser
'HTTP_FROM',                    // Sometimes, bots (especially Google) use a genuine UA but fill this header with their email address
'HTTP_X_SCANNER',               // Seen in use by Netsparker
'HTTP_SEC_CH_UA',               // Facebook omits itself in User-Agent but persists HeadlessChrome here for mobile requests
```

--------------------------------

### Import path for Crawlers fixture

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/Fixtures/Crawlers.md

Import statement to use the Crawlers class in your code.

```php
use Jaybizzle\CrawlerDetect\Fixtures\Crawlers;
```

--------------------------------

### compileRegex method signature

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Public method that compiles an array of regex patterns into a single non-capturing alternation string. The returned string is '(?:'.implode('|', $patterns).')', so preg_match's $matches[0] holds the full match. In normal use the constructor already compiles built-in fixtures; call this only to inspect compiled forms or reuse the join logic in tests.

```php
/**
 * Compile the regex patterns into one regex string.
 *
 * A non-capturing group is used because callers only need the full
 * match (preg_match's $matches[0]), not a back-reference.
 *
 * @param  array  $patterns
 * @return string
 */
public function compileRegex($patterns)
```

--------------------------------

### Passing headers from a request object

Source: https://github.com/jaybizzle/crawler-detect/blob/master/README.md

Pass headers from PSR-7, Symfony, or Swoole request objects to the constructor so CrawlerDetect can check all headers, not just User-Agent.

```php
// PSR-7 (Slim, Mezzio, Laminas, League)
$CrawlerDetect = new CrawlerDetect($request->getHeaders());

// Symfony HttpFoundation
$CrawlerDetect = new CrawlerDetect($request->headers->all());

// Swoole
$CrawlerDetect = new CrawlerDetect($request->header);

if ($CrawlerDetect->isCrawler()) {
    // ...
}
```

--------------------------------

### Section 2 exclusion patterns

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/Fixtures/Exclusions.md

Device and app names containing catch-all words like 'bot' to prevent false positives. Removing any of these entries changes detection results, not just timing.

```php
'cubot',
'; M bot',
'; CRONO',
'; B bot',
'; IDbot',
'; ID bot',
'; POWER BOT',
'OCTOPUS-CORE',
'htc_botdugls',
'super\/\d+\/Android\/\d+',
'"Yandex"',
'YandexModule2',
```

--------------------------------

### getUserAgent()

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/index.md

Returns the stored user agent string, or null if none is set.

```APIDOC
## Method: getUserAgent()

### Description
Returns the stored user agent string, or null if none is set.

### Request Example
```php
$CrawlerDetect->getUserAgent();                // string|null — stored agent
```

### Response
#### Success Response
- **string|null** - The stored user agent, or null if none is set
```

--------------------------------

### getMatches() distinguishing no match from no probe

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Both no match and no probe yield null. The second call shows a catch-all suffix pattern matching 'somenaughtybot'.

```php
$cd = new CrawlerDetect;
$cd->isCrawler('nothing to see here'); // false
var_dump($cd->getMatches());           // NULL

$cd->isCrawler('somenaughtybot');      // true — catch-all suffix pattern
var_dump($cd->getMatches());           // string(14) "somenaughtybot"
```

--------------------------------

### setHttpHeaders($headers)

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/index.md

Replaces the header map used for detection. Returns void.

```APIDOC
## Method: setHttpHeaders($headers)

### Description
Replaces the header map used for detection. Returns void.

### Parameters
- **$headers** (array) - Required - The new header map

### Request Example
```php
$CrawlerDetect->setHttpHeaders($headers);      // void — replace the header map
```

### Response
#### Success Response
- **void** - No return value
```

--------------------------------

### Passing PSR-7 headers and explicit user agent to CrawlerDetect

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Constructs CrawlerDetect with headers from a PSR-7 request and an explicit Googlebot user agent string. Useful for testing or when headers are not from $_SERVER.

```php
$CrawlerDetect = new CrawlerDetect(
    $request->getHeaders(),                     // string[][] — real header names
    'Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)'
);

if ($CrawlerDetect->isCrawler()) { /* ... */ }
```

--------------------------------

### setUserAgent($userAgent = null)

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Sets the user agent string to be probed. If null, it composes the agent from the HTTP headers present in the constructor's header map.

```APIDOC
## setUserAgent($userAgent = null)

### Description
Sets the user agent string to be probed. If null, it composes the agent from the HTTP headers present in the constructor's header map.

### Method
setUserAgent

### Parameters
- **$userAgent** (string|null) - Optional - The user-agent string to probe. When null, the agent is composed from the header map instead.

### Return Type
string|null - The newly stored agent; null if no explicit agent was given and none of the UA headers were present.

### Behavior
- If a non-null agent is passed, it is stored and returned as-is.
- Otherwise the values of every user-agent header present in `$this->httpHeaders` (in the order returned by `getUaHttpHeaders()`) are concatenated, space-separated. If no header was found, the stored value stays null.

### Example
```php
$cd = new CrawlerDetect;
$stored = $cd->setUserAgent('Mozilla/5.0 (compatible; Googlebot/2.1)');
// $stored === 'Mozilla/5.0 (compatible; Googlebot/2.1)'
// $cd->getUserAgent() === 'Mozilla/5.0 (compatible; Googlebot/2.1)'
```
```

--------------------------------

### getUserAgent() with header array

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Shows that when no explicit agent is given, the user agent is composed from the HTTP_USER_AGENT header.

```php
$cd = new CrawlerDetect(['HTTP_USER_AGENT' => 'Mozilla/5.0 (compatible; bingbot/2.0)']);

echo $cd->getUserAgent(); // 'Mozilla/5.0 (compatible; bingbot/2.0)'
```

--------------------------------

### Exclusions class declaration

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/Fixtures/Exclusions.md

Declares the Exclusions class extending AbstractProvider, providing the exclusion dataset for CrawlerDetect.

```php
namespace Jaybizzle\CrawlerDetect\Fixtures;

class Exclusions extends AbstractProvider
```

--------------------------------

### Class declaration for Headers

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/Fixtures/Headers.md

Declares the Headers class extending AbstractProvider. The class holds the list of HTTP header names that may carry a user-agent string.

```php
namespace Jaybizzle\CrawlerDetect\Fixtures;

class Headers extends AbstractProvider
```

--------------------------------

### setUserAgent with explicit user agent

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Creates a CrawlerDetect instance and sets a user agent string. The stored agent is returned and can be retrieved with getUserAgent().

```php
$cd = new CrawlerDetect;
$stored = $cd->setUserAgent('Mozilla/5.0 (compatible; Googlebot/2.1)');

// $stored === 'Mozilla/5.0 (compatible; Googlebot/2.1)'
// $cd->getUserAgent() === 'Mozilla/5.0 (compatible; Googlebot/2.1)'
```

--------------------------------

### Class declaration for Crawlers fixture

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/Fixtures/Crawlers.md

Declares the Crawlers class extending AbstractProvider, containing the crawler signature dataset.

```php
namespace Jaybizzle\CrawlerDetect\Fixtures;

class Crawlers extends AbstractProvider
```

--------------------------------

### setUserAgent method signature

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Defines the public setUserAgent method that accepts an optional user agent string. When null, it composes the agent from HTTP headers.

```php
/**
 * Set the user agent.
 *
 * @param  string|null  $userAgent
 */
public function setUserAgent($userAgent = null)
```

--------------------------------

### compileRegex

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Compiles an array of regex patterns into a single non-capturing alternation regex string. This is useful for inspecting compiled patterns or reusing the join logic.

```APIDOC
## compileRegex

### Description
Compiles an array of regex patterns into a single non-capturing alternation regex string. This is useful for inspecting compiled patterns or reusing the join logic.

### Method
compileRegex

### Endpoint
`compileRegex($patterns)`

### Parameters
#### Path Parameters
- `$patterns` (array) - Required - A list of regex patterns (strings) to join.

### Request Example
```php
use Jaybizzle\CrawlerDetect\CrawlerDetect;
use Jaybizzle\CrawlerDetect\Fixtures\Exclusions;

$cd = new CrawlerDetect;
$joined = $cd->compileRegex((new Exclusions)->getAll());
```

### Response
#### Success Response
- **Return type** (string) - The single regex `'(?:'.implode('|', $patterns).')'`: a non-capturing alternation of every pattern.

#### Response Example
```php
// $joined === '(?:Safari\/[\d\.]*|Firefox\/[\d\.]*|...)'
```
```

--------------------------------

### getUaHttpHeaders method signature

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Public method that returns the list of user-agent header names. The return type is array, containing the 11 SAPI-formatted header names from the Headers fixture, such as HTTP_USER_AGENT and HTTP_FROM.

```php
/**
 * Return user agent headers.
 *
 * @return array
 */
public function getUaHttpHeaders()
```

--------------------------------

### setHttpHeaders with PSR-7 style headers

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Sets HTTP headers using real header names with array values, as in PSR-7 or HttpFoundation requests. The 'User-Agent' header contains a bingbot user agent string; 'Host' is also provided.

```php
// PSR-7 / HttpFoundation style — real header names, array values
$cd = new CrawlerDetect;
$cd->setHttpHeaders([
    'User-Agent' => ['Mozilla/5.0 (compatible; bingbot/2.0; +http://www.bing.com/bingbot.htm)'],
    'Host'       => ['www.example.com'],
]);
```

--------------------------------

### CrawlerDetect::setUserAgent

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/configuration.md

Sets the user agent string to be used for detection. If null, composes from headers.

```APIDOC
## [METHOD] CrawlerDetect::setUserAgent

### Description
Sets the user agent string. If null, composes from the stored header map.

### Method
setUserAgent

### Signature
`public function setUserAgent($userAgent = null)`

### Parameters
- **$userAgent** (string|null) - Optional - Explicit user-agent string. Defaults to null.

### Request Example
```php
$crawlerDetect->setUserAgent($userAgent);
```

### Response
No return value.
```

--------------------------------

### compileRegex with preg_replace

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Applies the joined exclusions regex manually with preg_replace to remove crawler-like patterns from a user agent string. The regex is wrapped in delimiters and made case-insensitive with the 'i' flag.

```php
$exclusions = '/'.$cd->compileRegex((new Exclusions)->getAll()).'/i';
$clean = preg_replace($exclusions, '', $userAgent);
```

--------------------------------

### Section 1 exclusion patterns

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/Fixtures/Exclusions.md

Browser and platform tokens stripped for speed. These are PCRE patterns without delimiters; the consumer applies them case-insensitively. Each entry must be specific enough to avoid eating the character after the token.

```php
'Safari\/[\d\.]*',
'Firefox\/[\d\.]*',
' Chrome\/[\d\.]*',
'Chromium\/[\d\.]*',
'MSIE [\d\.]*',
'Opera\/[\d\.]*',
'Mozilla\/[\d\.]*',
'AppleWebKit\/[\d\.]*',
'Trident\/[\d\.]*',
'Windows NT [\d\.]*',
'Android [\d\.]*',
'Macintosh;',
'Ubuntu',
'Linux',
' Intel ',
'Mac OS X [\d_]*',
'(like )?Gecko(\/[\d\.]*)?',
'KHTML,',
'CriOS\/[\d\.]*',
'CPU iPhone OS ([0-9_])* like Mac OS X',
'CPU OS ([0-9_])* like Mac OS X',
'iPod',
'compatible',
'x86_..',
'i686',
'x64',
'X11',
'rv:[\d\.]*',
'Version\/[\d\.]*',
'WOW64',
'Win64',
'Dalvik\/[\d\.]*',
' \.NET CLR [\d\.]*',
'Presto\/[\d\.]*',
'Media Center PC',
'BlackBerry',
'Build\/',
'Opera Mini\/\d{1,2}\.\d{1,2}\.[\d\.]*\/\d{1,2}\.',
'Opera',
' \.NET[\d\.]*',
```

--------------------------------

### setHttpHeaders method signature

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Public method that sets HTTP headers for crawler detection. Accepts either _SERVER-style names (HTTP_USER_AGENT) or real header names from PSR-7, HttpFoundation, Swoole, or Lambda events ('User-Agent'), storing them under canonical HTTP_ form. Passing null or an empty array falls back to $_SERVER.

```php
/**
 * Set HTTP headers.
 *
 * Accepts either the _SERVER-style names PHP's SAPI produces
 * (HTTP_USER_AGENT) or the real header names carried by a PSR-7 request,
 * HttpFoundation, Swoole or a Lambda event ('User-Agent'). Both are stored
 * under the canonical HTTP_ form so lookups stay uniform.
 *
 * @param  array|null  $httpHeaders
 */
public function setHttpHeaders($httpHeaders = null)
```

--------------------------------

### setHttpHeaders reset to $_SERVER

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Passing an empty array to setHttpHeaders resets the headers to fall back to $_SERVER.

```php
$cd->setHttpHeaders([]);   // falls back to $_SERVER
```

--------------------------------

### CrawlerDetect exclusion usage

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/Fixtures/Exclusions.md

Shows indirect usage: CrawlerDetect strips these tokens before matching, so 'iPod' and 'Cubot X9' are not detected as crawlers.

```php
$cd = new CrawlerDetect;
var_dump($cd->isCrawler('iPod'));        // false — 'iPod' is stripped, then nothing left to match
var_dump($cd->isCrawler('Cubot X9'));    // false — 'cubot' is a phone brand, not a crawler
```

--------------------------------

### isCrawler basic usage

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Creates a CrawlerDetect instance and checks the current visitor. If isCrawler() returns true, responds with HTTP 403 or routes to a honeypot.

```php
$CrawlerDetect = new CrawlerDetect;

if ($CrawlerDetect->isCrawler()) {
    http_response_code(403); // or route to a honeypot, log, etc.
}
```

--------------------------------

### getMatches() method definition

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Returns the text matched by the last isCrawler() call, or null when there was no match. Matches do not persist across calls.

```php
/**
 * Return the matches.
 *
 * @return string|null
 */
public function getMatches()
```

--------------------------------

### getUaHttpHeaders

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Returns the list of user-agent header names that are considered for crawler detection. Useful for checking which UA headers are present in the current request.

```APIDOC
## getUaHttpHeaders

### Description
Returns the list of user-agent header names that are considered for crawler detection. Useful for checking which UA headers are present in the current request.

### Method
getUaHttpHeaders

### Endpoint
`getUaHttpHeaders()`

### Parameters
#### Path Parameters
None.

### Request Example
```php
$cd = new CrawlerDetect;

foreach ($cd->getUaHttpHeaders() as $header) {
    // 'HTTP_USER_AGENT', 'HTTP_FROM', ...
}
```

### Response
#### Success Response
- **Return type** (array) - The 11 SAPI-formatted header names that count as user-agent headers: `HTTP_USER_AGENT`, `HTTP_X_OPERAMINI_PHONE_UA`, `HTTP_X_DEVICE_USER_AGENT`, `HTTP_X_ORIGINAL_USER_AGENT`, `HTTP_X_SKYFIRE_PHONE`, `HTTP_X_BOLT_PHONE_UA`, `HTTP_DEVICE_STOCK_UA`, `HTTP_X_UCBROWSER_DEVICE_UA`, `HTTP_FROM`, `HTTP_X_SCANNER`, `HTTP_SEC_CH_UA`.

#### Response Example
```php
$present = array_intersect($cd->getUaHttpHeaders(), array_keys($_SERVER));
```
```

--------------------------------

### getMatches()

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Returns the text matched by the last isCrawler() call, or null if there was no match. Matches do not persist across calls.

```APIDOC
## getMatches()

### Description
Returns the text matched by the last `isCrawler()` call, or `null` if there was no match (including after an empty, excluded, or PCRE-erroring agent). Matches do not persist across calls: `isCrawler()` resets them first.

### Method
`getMatches`

### Parameters
None.

### Return Type
`string|null` — the text matched by the last `isCrawler()` call (`$this->matches[0]`), or `null` when there was no match.

### Examples
```php
$CrawlerDetect = new CrawlerDetect;

if ($CrawlerDetect->isCrawler()) {
    echo 'Matched: '.$CrawlerDetect->getMatches();
    // e.g. "Matched: monitoring" for Yahoo Ad monitoring
}
```

Distinguishing "no match" from "no probe" — both yield `null`:

```php
$cd = new CrawlerDetect;
$cd->isCrawler('nothing to see here'); // false
var_dump($cd->getMatches());           // NULL

$cd->isCrawler('somenaughtybot');      // true — catch-all suffix pattern
var_dump($cd->getMatches());           // string(14) "somenaughtybot"
```
```

--------------------------------

### isCrawler($userAgent = null)

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Checks the user agent string against the crawler regex. Returns true if a crawler signature matches, false otherwise. Handles PCRE errors gracefully by returning false without throwing exceptions.

```APIDOC
## isCrawler($userAgent = null)

### Description
Checks the user agent string against the crawler regex. Returns true if a crawler signature matches, false otherwise. Handles PCRE errors gracefully by returning false without throwing exceptions.

### Method
isCrawler

### Parameters
- **$userAgent** (string|null) - Optional - Agent string to check. null uses the stored agent (constructor value or composed from headers). An explicit argument is checked without altering the stored agent.

### Return Type
bool - true when a crawler signature matches, false otherwise.

### Behavior
1. Resets `$this->matches` to [].
2. Selects the probe string: `$userAgent ?: $this->userAgent ?: ''`.
3. Strips everything matched by `$compiledExclusions` (case-insensitive preg_replace). If the result is null or whitespace-only, returns false.
4. Trims and runs `preg_match("/{$this->compiledRegex}/i", $agent, $this->matches)` — case-insensitive against the joined crawler alternation.
5. If preg_match returns false (a PCRE error, e.g. backtrack limit exhaustion), `$this->matches` is reset and false is returned — no exception is thrown.
6. Otherwise returns `(bool) $result`; on a match, `$this->matches[0]` holds the matched text.

### Example
```php
$CrawlerDetect = new CrawlerDetect;
if ($CrawlerDetect->isCrawler()) {
    http_response_code(403); // or route to a honeypot, log, etc.
}
```
```

--------------------------------

### CrawlerDetect::setHttpHeaders

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/configuration.md

Sets the HTTP headers to be used for detection. Accepts an array of headers, with fallback to $_SERVER if null or empty.

```APIDOC
## [METHOD] CrawlerDetect::setHttpHeaders

### Description
Sets the header map used for detection. If null or empty, falls back to global $_SERVER.

### Method
setHttpHeaders

### Signature
`public function setHttpHeaders($httpHeaders = null)`

### Parameters
- **$httpHeaders** (array|null) - Optional - Header map to probe. Defaults to null.

### Request Example
```php
$crawlerDetect->setHttpHeaders($headers);
```

### Response
No return value.
```

--------------------------------

### isCrawler($userAgent)

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/index.md

Checks whether the current/stored agent or an explicit string is a crawler. Returns a boolean.

```APIDOC
## Method: isCrawler($userAgent)

### Description
Checks whether the current/stored agent or an explicit string is a crawler. Returns a boolean.

### Parameters
- **$userAgent** (string) - Optional - User agent string to check; if omitted, uses the stored agent

### Request Example
```php
$CrawlerDetect->isCrawler();                   // bool — check the current/stored agent
$CrawlerDetect->isCrawler('SomeBot/1.0');      // bool — check an explicit string
```

### Response
#### Success Response
- **bool** - true if the agent is a crawler, false otherwise
```

--------------------------------

### Basic usage of CrawlerDetect with isCrawler()

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Detects crawlers for the current visitor, falling back to $_SERVER when no headers are provided. Calls isCrawler() to check the user agent.

```php
use Jaybizzle\CrawlerDetect\CrawlerDetect;

$CrawlerDetect = new CrawlerDetect;

if ($CrawlerDetect->isCrawler()) {
    // current visitor's headers contain a crawler signature
}
```

--------------------------------

### isCrawler error-tolerant usage

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Demonstrates that PCRE errors during preg_match degrade to false without throwing an exception, so the result can be treated as a plain boolean.

```php
$cd = new CrawlerDetect;
$isBot = $cd->isCrawler('Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)');

// On PCRE error: $isBot === false, $cd->getMatches() === null — never an exception
```

--------------------------------

### setHttpHeaders

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Sets the HTTP headers to be used for crawler detection. Accepts either _SERVER-style names or real header names, normalizing them for uniform lookups.

```APIDOC
## setHttpHeaders

### Description
Sets the HTTP headers to be used for crawler detection. Accepts either _SERVER-style names or real header names, normalizing them for uniform lookups.

### Method
setHttpHeaders

### Endpoint
`setHttpHeaders($httpHeaders = null)`

### Parameters
#### Path Parameters
- `$httpHeaders` (array|null) - Optional - Header map (mixed header names, scalar or array-of-string values). `null` or an empty array causes a fallback to `$_SERVER`.

### Request Example
```php
$cd = new CrawlerDetect;
$cd->setHttpHeaders([
    'User-Agent' => ['Mozilla/5.0 (compatible; bingbot/2.0; +http://www.bing.com/bingbot.htm)'],
    'Host'       => ['www.example.com'],
]);
```

### Response
#### Success Response
- **Return type** (void) - No explicit return.

#### Response Example
```php
$cd->setHttpHeaders([]);   // falls back to $_SERVER
```
```

--------------------------------

### Class declaration for Jaybizzle\CrawlerDetect\CrawlerDetect

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Declares the CrawlerDetect class in the Jaybizzle\CrawlerDetect namespace. This is the library's single entry-point class for detecting crawlers.

```php
namespace Jaybizzle\CrawlerDetect;

class CrawlerDetect
```

--------------------------------

### isCrawler method signature

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Defines the public isCrawler method that checks a user agent string against the crawler regex. Accepts an optional agent; null uses the stored agent.

```php
/**
 * Check user agent string against the regex.
 *
 * @param  string|null  $userAgent
 * @return bool
 */
public function isCrawler($userAgent = null)
```

--------------------------------

### getUaHttpHeaders intersection with $_SERVER

Source: https://github.com/jaybizzle/crawler-detect/blob/master/_autodocs/api-reference/CrawlerDetect.md

Checks which user-agent headers are present in the current request by intersecting the list from getUaHttpHeaders with the keys of $_SERVER.

```php
$present = array_intersect($cd->getUaHttpHeaders(), array_keys($_SERVER));
```
Tokens:
Raw