reCAPTCHA PHP Client Library

https://github.com/google/recaptcha
Admin
A PHP library that wraps Google's reCAPTCHA server-side verification for protecting websites from...
Tokens:38,630
Snippets:270
Trust Score:10
License:BSD-3-Clause
Update:1 month ago
Show doc for...
Tokens:
Raw
### Serve examples locally

Source: https://github.com/google/recaptcha/blob/main/AGENTS.md

Starts a PHP built-in server at http://localhost:8080 to manually test the interactive example pages locally.

```bash
composer run serve-examples
# Starts PHP built-in server at http://localhost:8080 serving examples/
```

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

### Serve reCAPTCHA examples locally with Composer

Source: https://github.com/google/recaptcha/blob/main/README.md

Run the reCAPTCHA examples locally using the Composer script, which starts the PHP dev server at http://localhost:8080/.

```sh
composer run-script serve-examples
```

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

### Install dependencies with composer install

Source: https://github.com/google/recaptcha/blob/main/README.md

Installs the project dependencies after cloning the repository. Run this command from the project root to set up your local checkout.

```bash
composer install
```

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

### Direct download usage with autoload.php

Source: https://github.com/google/recaptcha/blob/main/README.md

Direct download installation example. Requires the autoloader script and then instantiates the ReCaptcha class with your secret key.

```php
require_once '/path/to/recaptcha/src/autoload.php';
$recaptcha = new \ReCaptcha\ReCaptcha($secret);
```

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

### Post constructor usage

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/RequestMethod-Post.md

Usage example for the Post constructor. Shows how to force the file_get_contents() transport and how to use an alternative endpoint with a custom timeout.

```php
use ReCaptcha\ReCaptcha;
use ReCaptcha\RequestMethod\Post;

// Explicitly force the file_get_contents() transport (pre-1.4.2 behavior)
$recaptcha = new ReCaptcha($secret, new Post());

// Alternative endpoint and custom timeout
$recaptcha = new ReCaptcha($secret, new Post(ReCaptcha::SITE_VERIFY_URL_ALTERNATIVE, 10));
```

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

### Install google/recaptcha with Composer

Source: https://github.com/google/recaptcha/blob/main/README.md

Adds the google/recaptcha package as a dependency to your project. Requires Composer to be installed.

```sh
composer require google/recaptcha "^2.0"
```

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

### PHP array configuration template for reCAPTCHA example keys

Source: https://github.com/google/recaptcha/blob/main/_autodocs/configuration.md

Template for the fallback config.php file, used by example scripts when the corresponding RECAPTCHA_* environment variables are empty. The keys 'v2-standard', 'v2-invisible', and 'v3' hold dummy site and secret keys that are replaced with real credentials.

```php
return [
    'v2-standard' => ['site' => '', 'secret' => ''],
    'v2-invisible' => ['site' => '', 'secret' => ''],
    'v3' => ['site' => '', 'secret' => ''],
];
```

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

### Using SocketPost with ReCaptcha

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/RequestMethod-SocketPost.md

Usage example showing how to instantiate ReCaptcha with the SocketPost request method. Requires the SocketPost class and a secret key.

```php
use ReCaptcha\ReCaptcha;
use ReCaptcha\RequestMethod\SocketPost;

$recaptcha = new ReCaptcha($secret, new SocketPost());
```

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

### AppEngine Flexible environment config (app.yaml)

Source: https://github.com/google/recaptcha/blob/main/_autodocs/configuration.md

Configuration for Google AppEngine Flexible environment, hosting the examples directory as document root and excluding tests. Intended for the hosted demo only, not part of the library runtime.

```yaml
runtime: php
env: flex
skip_files:
- tests
runtime_config:
  document_root: examples
```

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

### toArray usage example

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/Response.md

Shows how to create a Response from JSON and convert it to an array using toArray(). The output is an associative array with the documented keys.

```php
use ReCaptcha\Response;

$resp = Response::fromJson('{"success": false, "error-codes": ["timeout-or-duplicate"]}');
$data = $resp->toArray();
// ['success' => false, 'hostname' => '', 'challenge_ts' => '', 'apk_package_name' => '',
//  'score' => null, 'action' => '', 'error-codes' => ['timeout-or-duplicate']]
```

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

### Add google/recaptcha to composer.json

Source: https://github.com/google/recaptcha/blob/main/README.md

Alternative installation method by adding the dependency directly to your composer.json file.

```json
"require": {
    "google/recaptcha": "^2.0"
}
```

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

### Constructing RequestParameters

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/RequestParameters.md

Example of constructing a RequestParameters instance with all four parameters: secret, response token, remote IP, and client version. The remoteIp and version parameters are optional and default to null.

```php
use ReCaptcha\RequestParameters;

$params = new RequestParameters(
    'your-secret',
    '03AFcWe...',   // user response token
    '203.0.113.10', // remote IP
    'php_2.1.0'     // client version
);
```

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

### Using RequestParameters::toQueryString

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/RequestParameters.md

Example of using toQueryString to generate the POST body. The output is shown in the comment: a URL-encoded query string with all four parameters.

```php
use ReCaptcha\RequestParameters;

$params = new RequestParameters('secret', 'token', '203.0.113.10', 'php_2.1.0');
$body = $params->toQueryString();
// "secret=secret&response=token&remoteip=203.0.113.10&version=php_2.1.0"
```

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

### Handling connection failures with Post

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/RequestMethod-Post.md

Usage example handling transport failures. Checks for ReCaptcha::E_CONNECTION_FAILED error code and suggests considering SocketPost as an alternative.

```php
use ReCaptcha\ReCaptcha;
use ReCaptcha\RequestMethod\Post;

$recaptcha = new ReCaptcha($secret, new Post(ReCaptcha::SITE_VERIFY_URL_ALTERNATIVE, 30));
$resp = $recaptcha->verify($token);

if (!$resp->isSuccess()) {
    $codes = $resp->getErrorCodes();
    if (in_array(ReCaptcha::E_CONNECTION_FAILED, $codes)) {
        // General network failure or allow_url_open disabled —
        // consider ReCaptcha\RequestMethod\SocketPost instead.
    }
}
```

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

### jsonSerialize usage example

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/Response.md

Shows how to encode a Response object directly with json_encode(), which uses jsonSerialize() to produce the same shape as toArray().

```php
$resp = $recaptcha->verify($token, $remoteAddr);
header('Content-type: application/json');
echo json_encode($resp); // uses jsonSerialize() -> same shape as toArray()
```

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

### RequestParameters::toArray implementation

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/RequestParameters.md

Implementation of toArray. It builds the parameter array starting with secret and response, then conditionally adds remoteip and version only when the corresponding properties are not null.

```php
$params = ['secret' => $this->secret, 'response' => $this->response];

if (!is_null($this->remoteIp)) {
    $params['remoteip'] = $this->remoteIp;
}
if (!is_null($this->version)) {
    $params['version'] = $this->version;
}
return $params;
```

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

### Instantiate ReCaptcha and verify response

Source: https://github.com/google/recaptcha/blob/main/ARCHITECTURE.md

Shows the basic usage: create a ReCaptcha instance with the secret key, set expected hostname, and call verify() with the response and IP. If successful, the code proceeds; otherwise, error codes are retrieved.

```php
<?php
$recaptcha = new \ReCaptcha\ReCaptcha($secret);
$resp = $recaptcha->setExpectedHostname('recaptcha-demo.appspot.com')
                  ->verify($gRecaptchaResponse, $remoteIp);
if ($resp->isSuccess()) {
    // Verified!
} else {
    $errors = $resp->getErrorCodes();
}
```

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

### Post::__construct

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/RequestMethod-Post.md

Constructor for the Post request method. Initializes the site verify URL and timeout for the request.

```APIDOC
## Post::__construct

### Description
Constructor for the Post request method. Initializes the site verify URL and timeout for the request.

### Method
Constructor

### Signature
```php
public function __construct(?string $siteVerifyUrl = null, int $timeout = 60)
```

### Parameters
- **siteVerifyUrl** (?string) - Optional - URL for reCAPTCHA siteverify API. When null, falls back to `https://www.google.com/recaptcha/api/siteverify`.
- **timeout** (int) - Optional - Timeout in seconds for the request (applied to the stream context). Default: 60.

### Usage Example
```php
use ReCaptcha\ReCaptcha;
use ReCaptcha\RequestMethod\Post;

// Explicitly force the file_get_contents() transport (pre-1.4.2 behavior)
$recaptcha = new ReCaptcha($secret, new Post());

// Alternative endpoint and custom timeout
$recaptcha = new ReCaptcha($secret, new Post(ReCaptcha::SITE_VERIFY_URL_ALTERNATIVE, 10));
```
```

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

### Basic usage of SocketPost with ReCaptcha client

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/RequestMethod-SocketPost.md

Shows how to instantiate ReCaptcha with a SocketPost request method and verify a response key. Requires a secret key and a SocketPost instance.

```php
use ReCaptcha\ReCaptcha;
use ReCaptcha\RequestMethod\SocketPost;

$recaptcha = new ReCaptcha($secret, new SocketPost());
$resp = $recaptcha->setExpectedHostname('recaptcha-demo.appspot.com')
                  ->verify($responseKey, $remoteAddr);
```

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

### Basic usage

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/ReCaptcha.md

Basic instantiation with a secret key.

```php
use ReCaptcha\ReCaptcha;

$recaptcha = new ReCaptcha('your-secret-key');
```

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

### Response::__construct

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/Response.md

Creates a new Response instance with the verification result and optional metadata.

```APIDOC
## Response::__construct

### Description
Creates a new Response instance with the verification result and optional metadata.

### Method
Constructor

### Signature
```php
public function __construct(
    private bool $success,
    private array $errorCodes = [],
    private string $hostname = '',
    private string $challengeTs = '',
    private string $apkPackageName = '',
    private ?float $score = null,
    private string $action = '',
) {}
```

### Parameters
- `success` (bool) - Required - Success or failure of the verification
- `errorCodes` (array of string) - Optional - Error code strings
- `hostname` (string) - Optional - Hostname of the site where the reCAPTCHA was solved
- `challengeTs` (string) - Optional - Timestamp of the challenge load (ISO format `yyyy-MM-dd'T'HH:mm:ssZZ`)
- `apkPackageName` (string) - Optional - APK package name
- `score` (?float) - Optional - Score assigned to the request (0.0–1.0); `null` for v2 or absent
- `action` (string) - Optional - Action as specified by the page
```

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

### Run mandatory quality gates

Source: https://github.com/google/recaptcha/blob/main/AGENTS.md

Run all five mandatory quality gates before creating a commit or opening a pull request. Ensure zero errors or warnings from each command.

```bash
# 1. Validate composer.json and composer.lock
composer validate --strict

# 2. Check for known security vulnerabilities in dependencies
composer audit

# 3. Check code formatting and strict_types enforcement (PHP-CS-Fixer)
composer run lint
# (Use `composer run lint-fix` to automatically format files)

# 4. Run static analysis at max level + strict rules + PHPUnit rules (PHPStan)
composer run phpstan

# 5. Run unit tests with Xdebug coverage and strict PHPUnit 13 checks
composer run test
```

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

### Run tests with composer run test

Source: https://github.com/google/recaptcha/blob/main/README.md

Runs the test suite. Ensure you add or update tests to cover any changes before submitting a pull request.

```bash
composer run test
```

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

### CurlPost usage with ReCaptcha

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/RequestMethod-CurlPost.md

Shows how to instantiate CurlPost with default or custom settings and pass it to ReCaptcha. The alternative endpoint uses ReCaptcha::SITE_VERIFY_URL_ALTERNATIVE.

```php
use ReCaptcha\ReCaptcha;
use ReCaptcha\RequestMethod\CurlPost;

// Defaults: standard Google endpoint, 60s timeout
$curl = new CurlPost();

// Alternative endpoint (recaptcha.net) with a 10s timeout
$curl = new CurlPost(ReCaptcha::SITE_VERIFY_URL_ALTERNATIVE, 10);

$recaptcha = new ReCaptcha($secret, $curl);
```

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

### Chain set*() methods for v3 verification

Source: https://github.com/google/recaptcha/blob/main/README.md

Chained verification using setExpectedHostname(), setExpectedAction(), and setScoreThreshold() before verify(). Each set*() method returns the ReCaptcha instance for chaining.

```php
<?php
$recaptcha = new \ReCaptcha\ReCaptcha($secret);
$resp = $recaptcha->setExpectedHostname('recaptcha-demo.appspot.com')
                  ->setExpectedAction('homepage')
                  ->setScoreThreshold(0.5)
                  ->verify($gRecaptchaResponse, $remoteIp);

if ($resp->isSuccess()) {
    // Verified!
} else {
    $errors = $resp->getErrorCodes();
}
```

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

### Stream context options for submit

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/RequestMethod-Post.md

Stream context options built by submit(). Configures SSL peer verification, POST method, content type header, request body, timeout, and ignore_errors.

```php
$options = [
    'ssl' => [
        'verify_peer'      => true,
        'verify_peer_name' => true,
    ],
    'http' => [
        'header'         => "Content-type: application/x-www-form-urlencoded\r\n",
        'method'         => 'POST',
        'content'        => $params->toQueryString(),
        'timeout'        => $this->timeout,
        'ignore_errors'  => true,
    ],
];
```

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

### withExpectedApkPackageName

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/ReCaptcha.md

Immutable counterpart of `setExpectedApkPackageName`. Clones the instance, applies the setting, and returns the clone.

```APIDOC
## withExpectedApkPackageName

### Description
Immutable counterpart of `setExpectedApkPackageName`. Clones the instance, applies the setting to the clone, and returns it.

### Method
withExpectedApkPackageName

### Signature
`public function withExpectedApkPackageName(string $apkPackageName): self`

### Parameters
- **apkPackageName** (string) - Required - Expected APK package name.

### Return
`self` (the cloned instance) for fluent chaining.

### Usage Example
```php
$recaptcha = (new ReCaptcha($secret))->withExpectedApkPackageName('com.example.myapp');
```
```

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

### Run lint, phpstan, and test via Composer

Source: https://github.com/google/recaptcha/blob/main/CONTRIBUTING.md

Run the PHP Coding Standards Fixer, PHPStan, and PHPUnit through Composer scripts. These commands are executed automatically by GitHub Actions on pull requests, but running them locally before submission helps avoid bounced changes.

```sh
composer run lint
composer run phpstan
composer run test
```

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

### CurlPost::__construct

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/RequestMethod-CurlPost.md

Creates a new CurlPost instance with an optional custom siteverify URL and timeout.

```APIDOC
## CurlPost::__construct

### Description
Creates a new CurlPost instance. The siteVerifyUrl defaults to the standard Google reCAPTCHA siteverify endpoint, and the timeout defaults to 60 seconds.

### Method
Constructor

### Signature
```php
public function __construct(?string $siteVerifyUrl = null, int $timeout = 60)
```

### Parameters
- **siteVerifyUrl** (?string) - Optional - URL for reCAPTCHA siteverify API. When null, falls back to `https://www.google.com/recaptcha/api/siteverify`.
- **timeout** (int) - Optional - Timeout in seconds for the request (applied to both connect and transfer). Default: 60.

### Usage Example
```php
use ReCaptcha\ReCaptcha;
use ReCaptcha\RequestMethod\CurlPost;

// Defaults: standard Google endpoint, 60s timeout
$curl = new CurlPost();

// Alternative endpoint (recaptcha.net) with a 10s timeout
$curl = new CurlPost(ReCaptcha::SITE_VERIFY_URL_ALTERNATIVE, 10);

$recaptcha = new ReCaptcha($secret, $curl);
```
```

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

### RequestMethod constructor signature with siteVerifyUrl and timeout

Source: https://github.com/google/recaptcha/blob/main/_autodocs/configuration.md

Shared constructor signature for all three RequestMethod implementations (CurlPost, Post, SocketPost). The timeout default is 60 seconds and applies differently: to CURLOPT_CONNECTTIMEOUT and CURLOPT_TIMEOUT for CurlPost, to the stream timeout option for Post, and to connection and read timeouts for SocketPost. The siteVerifyUrl defaults to ReCaptcha::SITE_VERIFY_URL unless overridden, and you can use ReCaptcha::SITE_VERIFY_URL_ALTERNATIVE when www.google.com is not accessible.

```php
public function __construct(?string $siteVerifyUrl = null, int $timeout = 60)
```

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

### withExpectedApkPackageName usage

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/ReCaptcha.md

Immutable version of setExpectedApkPackageName. Clones the instance, applies the setting, and returns the clone.

```php
$recaptcha = (new ReCaptcha($secret))->withExpectedApkPackageName('com.example.myapp');
```

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

### withExpectedHostname usage

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/ReCaptcha.md

Usage of withExpectedHostname. It creates a base ReCaptcha instance with the hostname set, then chains withExpectedAction and withScoreThreshold to create a new verifier. The base instance remains unmodified.

```php
use ReCaptcha\ReCaptcha;

$baseRecaptcha = (new ReCaptcha($secret))->withExpectedHostname('recaptcha-demo.appspot.com');
// $baseRecaptcha is unmodified by subsequent with*() calls
$v3Verifier = $baseRecaptcha->withExpectedAction('homepage')->withScoreThreshold(0.5);
```

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

### Skeleton for a new RequestMethod implementation

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/RequestMethod.md

Skeleton for creating a new request method. The convention is to name the class RequestMethod\_MethodType_Post. Implement submit() to POST the query string to the siteverify endpoint, returning the appropriate synthetic JSON error payload on network failure or non-200 response.

```php
use ReCaptcha\RequestMethod;
use ReCaptcha\RequestParameters;

class MyPost implements RequestMethod
{
    public function submit(RequestParameters $params): string
    {
        // POST $params->toQueryString() to the siteverify endpoint.
        // On network failure return '{"success": false, "error-codes": ["connection-failed"]}'.
        // On non-200 response return '{"success": false, "error-codes": ["bad-response"]}'.
    }
}
```

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

### Handling transport failures with SocketPost and error codes

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/RequestMethod-SocketPost.md

Demonstrates using SocketPost with an alternative URL and timeout, then checking error codes for connection failures or bad responses. Useful for diagnosing TLS socket issues or non-200 responses.

```php
use ReCaptcha\ReCaptcha;
use ReCaptcha\RequestMethod\SocketPost;

$recaptcha = new ReCaptcha($secret, new SocketPost(ReCaptcha::SITE_VERIFY_URL_ALTERNATIVE, 10));
$resp = $recaptcha->verify($token);

if (!$resp->isSuccess()) {
    foreach ($resp->getErrorCodes() as $code) {
        if (ReCaptcha::E_CONNECTION_FAILED === $code) {
            // could not open/use the TLS socket — check outbound port 443
        }
        if (ReCaptcha::E_BAD_RESPONSE === $code) {
            // non-200 status line or response without a body
        }
    }
}
```

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

### Basic verify usage

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/ReCaptcha.md

Basic usage of the verify method. It creates a ReCaptcha instance with the secret, calls verify with the response token from the form field and the user's IP, then checks isSuccess().

```php
use ReCaptcha\ReCaptcha;

$recaptcha = new ReCaptcha($secret);
$response  = $recaptcha->verify(
    $_POST[ReCaptcha::RESPONSE_KEY],
    $_SERVER['REMOTE_ADDR']
);

if ($response->isSuccess()) {
    // Verified!
}
```

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

### getAction method signature

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/Response.md

Returns the action as specified by the page; '' if absent or not a string. Used for the action-mismatch check.

```php
public function getAction(): string
```

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

### toArray method signature

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/Response.md

Returns an associative array with exactly these keys: success, hostname, challenge_ts, apk_package_name, score, action, error-codes.

```php
public function toArray(): array
```

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

### ReCaptcha\Response

Source: https://github.com/google/recaptcha/blob/main/_autodocs/types.md

Documentation for the ReCaptcha\Response class, including its constructor, methods, and properties.

```APIDOC
## ReCaptcha\Response

### Description
Immutable value object representing the result of a reCAPTCHA verification. It implements `\JsonSerializable` and provides typed accessors for all verification fields.

### Constructor
`__construct(bool $success, array $errorCodes = [], string $hostname = '', string $challengeTs = '', string $apkPackageName = '', ?float $score = null, string $action = '')`

### Methods

#### fromJson(string $json): Response
- **Description**: Creates a `Response` instance from a JSON string.
- **Parameters**:
  - `$json` (string) - Required - JSON string to parse.
- **Returns**: `Response`

#### isSuccess(): bool
- **Description**: Returns the verification success flag.
- **Returns**: `bool`

#### getErrorCodes(): array
- **Description**: Returns the list of error code strings.
- **Returns**: `array<string>`

#### getHostname(): string
- **Description**: Returns the hostname where the reCAPTCHA was solved.
- **Returns**: `string`

#### getChallengeTs(): string
- **Description**: Returns the challenge timestamp in ISO `yyyy-MM-dd'T'HH:mm:ssZZ` format.
- **Returns**: `string`

#### getApkPackageName(): string
- **Description**: Returns the APK package name.
- **Returns**: `string`

#### getScore(): ?float
- **Description**: Returns the v3 score (0.0–1.0).
- **Returns**: `?float`

#### getAction(): string
- **Description**: Returns the page action.
- **Returns**: `string`

#### toArray(): array
- **Description**: Returns the response as an associative array.
- **Returns**: `array`

#### jsonSerialize(): array
- **Description**: Returns the response as an array for JSON serialization.
- **Returns**: `array`

### Properties

| Property | Type | Required | Description |
|---|---|---|---|
| `success` | `bool` | yes | Verification success flag |
| `errorCodes` | `array<string>` | no (`[]`) | Error code strings |
| `hostname` | `string` | no (`''`) | Hostname where the reCAPTCHA was solved |
| `challengeTs` | `string` | no (`''`) | Challenge timestamp, ISO `yyyy-MM-dd'T'HH:mm:ssZZ` |
| `apkPackageName` | `string` | no (`''`) | APK package name |
| `score` | `?float` | no (`null`) | v3 score (0.0–1.0) |
| `action` | `string` | no (`''`) | Page action |

### Returned By
- `ReCaptcha\ReCaptcha::verify()`
- `Response::fromJson()`
```

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

### getChallengeTs method signature

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/Response.md

Returns the ISO 8601 challenge timestamp (yyyy-MM-dd'T'HH:mm:ssZZ); '' if absent or not a string. Used for the challenge-timeout check.

```php
public function getChallengeTs(): string
```

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

### \ReCaptcha\ReCaptcha::withExpectedHostname()

Source: https://github.com/google/recaptcha/blob/main/README.md

Immutable counterpart of setExpectedHostname(). Returns a cloned ReCaptcha instance.

```APIDOC
## \ReCaptcha\ReCaptcha::withExpectedHostname()

### Description
Immutable counterpart of `setExpectedHostname()`. Returns a cloned `ReCaptcha` instance with the expected hostname set.

### Method
withExpectedHostname

### Parameters
- **$hostname** (string) - Required - The expected hostname.

### Request Example
```php
$baseRecaptcha = (new \ReCaptcha\ReCaptcha($secret))->withExpectedHostname('recaptcha-demo.appspot.com');
```

### Response
Returns a cloned `ReCaptcha` instance.
```

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

### setExpectedHostname method signature

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/ReCaptcha.md

Signature of the setExpectedHostname method. It sets the expected hostname and returns the current instance for fluent chaining. Must be set if domain/package name validation is disabled.

```php
public function setExpectedHostname(string $hostname): self
```

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

### ReCaptcha\ReCaptcha::verify

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/ReCaptcha.md

Runs the server-side verification flow for a reCAPTCHA response token. It sends the token and secret to the siteverify service and returns a Response object.

```APIDOC
## ReCaptcha\ReCaptcha::verify

### Description
Runs the server-side verification flow for a reCAPTCHA response token. It sends the token and secret to the siteverify service and returns a Response object.

### Method
verify

### Signature
public function verify(string $response, string $remoteIp = null): Response

### Parameters
- **response** (string) - Required - The user response token from the reCAPTCHA widget (e.g., `$_POST[ReCaptcha::RESPONSE_KEY]`).
- **remoteIp** (string|null) - Optional - The user's IP address to include in the verification request.

### Returns
- **Response** - The verification result, containing success status and error codes.

### Example
```php
$recaptcha = new \ReCaptcha\ReCaptcha($secret);
$response = $recaptcha->verify($_POST['g-recaptcha-response'], $_SERVER['REMOTE_ADDR']);
if ($response->isSuccess()) {
    // verified
} else {
    $errors = $response->getErrorCodes();
}
```
```

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

### \ReCaptcha\ReCaptcha::withExpectedApkPackageName()

Source: https://github.com/google/recaptcha/blob/main/README.md

Immutable counterpart of setExpectedApkPackageName(). Returns a cloned ReCaptcha instance.

```APIDOC
## \ReCaptcha\ReCaptcha::withExpectedApkPackageName()

### Description
Immutable counterpart of `setExpectedApkPackageName()`. Returns a cloned `ReCaptcha` instance with the expected APK package name set.

### Method
withExpectedApkPackageName

### Parameters
- **$apkPackageName** (string) - Required - The expected Android package name.

### Request Example
```php
$baseRecaptcha = (new \ReCaptcha\ReCaptcha($secret))->withExpectedApkPackageName('com.example.app');
```

### Response
Returns a cloned `ReCaptcha` instance.
```

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

### Explicit transport with alternative endpoint

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/ReCaptcha.md

Instantiation with explicit CurlPost transport and alternative endpoint URL.

```php
use ReCaptcha\ReCaptcha;
use ReCaptcha\RequestMethod\CurlPost;

$recaptcha = new ReCaptcha(
    'your-secret-key',
    new CurlPost(ReCaptcha::SITE_VERIFY_URL_ALTERNATIVE, 10)
);
```

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

### Validate code quality with composer commands

Source: https://github.com/google/recaptcha/blob/main/README.md

Checks code quality and formatting before committing. Runs strict validation, security audit, static analysis with PHPStan, and automatic lint fixes.

```bash
composer validate --strict
composer audit
composer run phpstan
composer run lint-fix
```

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

### Transport selection logic

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/ReCaptcha.md

Default transport selection when $requestMethod is null. Uses CurlPost if curl is available, otherwise Post.

```php
if (null !== $requestMethod) {
    $this->requestMethod = $requestMethod;
} elseif (function_exists('curl_version')) {
    $this->requestMethod = new RequestMethod\CurlPost();
} else {
    $this->requestMethod = new RequestMethod\Post();
}
```

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

### setExpectedHostname usage

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/ReCaptcha.md

Usage of setExpectedHostname. It sets the expected hostname on the instance. Per the README, you must set this if you have disabled 'Domain/Package Name Validation' for your credentials.

```php
$recaptcha = new ReCaptcha($secret);
$recaptcha->setExpectedHostname('recaptcha-demo.appspot.com');
```

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

### ReCaptcha::__construct

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/ReCaptcha.md

Constructor for the ReCaptcha class, initializing the secret key and request method.

```APIDOC
## ReCaptcha::__construct

### Description
Creates a new ReCaptcha instance with the shared secret key and an optional request method for communicating with the siteverify service.

### Method
Constructor

### Signature
```php
public function __construct(#[\SensitiveParameter] string $secret, ?RequestMethod $requestMethod = null)
```

### Parameters
- **secret** (string) - Required - The shared key between your site and reCAPTCHA. Must be non-empty.
- **requestMethod** (?RequestMethod) - Optional - Method used to send the request to the `siteverify` service. When `null`, the constructor picks it automatically: `RequestMethod\CurlPost` if `curl_version()` is available, otherwise `RequestMethod\Post`.

### Throws
- **\RuntimeException** - If `$secret` is the empty string `''` (message: `'No secret provided'`).

### Request Example
```php
use ReCaptcha\ReCaptcha;

$recaptcha = new ReCaptcha('your-secret-key');
```

### Response
No return value. The constructor initializes the instance.

```

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

### Error handling

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/ReCaptcha.md

Catches RuntimeException when secret is empty.

```php
use ReCaptcha\ReCaptcha;

try {
    $recaptcha = new ReCaptcha('');
} catch (\RuntimeException $e) {
    // "No secret provided"
    error_log($e->getMessage());
}
```

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

### getApkPackageName method signature

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/Response.md

Returns the APK package name; '' if absent or not a string. Used for the APK-package-name check.

```php
public function getApkPackageName(): string
```

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

### Response::__construct constructor

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/Response.md

Constructor for the ReCaptcha\Response DTO. All parameters are promoted to readonly properties; defaults are provided for optional fields. The $score parameter is nullable and defaults to null for v2 or absent scores.

```php
public function __construct(
    private bool $success,
    private array $errorCodes = [],
    private string $hostname = '',
    private string $challengeTs = '',
    private string $apkPackageName = '',
    private ?float $score = null,
    private string $action = '',
) {}
```

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

### ReCaptcha\ReCaptcha

Source: https://github.com/google/recaptcha/blob/main/_autodocs/types.md

The ReCaptcha client class with its constructor, verification method, and fluent configuration methods.

```APIDOC
## ReCaptcha\ReCaptcha (class)

### Description
The client class for verifying reCAPTCHA responses. It provides a fluent interface for setting expected hostname, APK package name, action, score threshold, and challenge timeout, and a `verify()` method to perform the verification.

### Constructor
`__construct(#[\SensitiveParameter] string $secret, ?RequestMethod $requestMethod = null)`

### Methods

#### verify
`public function verify(string $response, ?string $remoteIp = null): Response`

Verifies a reCAPTCHA response. Returns a `Response` object.

#### setExpectedHostname / withExpectedHostname
`public function setExpectedHostname(string $hostname): self`
`public function withExpectedHostname(string $hostname): self`

Sets the expected hostname. Returns `self` for chaining.

#### setExpectedApkPackageName / withExpectedApkPackageName
`public function setExpectedApkPackageName(string $apkPackageName): self`
`public function withExpectedApkPackageName(string $apkPackageName): self`

Sets the expected APK package name. Returns `self` for chaining.

#### setExpectedAction / withExpectedAction
`public function setExpectedAction(string $action): self`
`public function withExpectedAction(string $action): self`

Sets the expected action. Returns `self` for chaining.

#### setScoreThreshold / withScoreThreshold
`public function setScoreThreshold(float $threshold): self`
`public function withScoreThreshold(float $threshold): self`

Sets the score threshold. Returns `self` for chaining.

#### setChallengeTimeout / withChallengeTimeout
`public function setChallengeTimeout(int $timeoutSeconds): self`
`public function withChallengeTimeout(int $timeoutSeconds): self`

Sets the challenge timeout in seconds. Returns `self` for chaining.

### Constants
- `VERSION` = 'php_2.1.0'
- `SITE_VERIFY_URL` = 'https://www.google.com/recaptcha/api/siteverify'
- `SITE_VERIFY_URL_ALTERNATIVE` = 'https://www.recaptcha.net/recaptcha/api/siteverify'
- `RESPONSE_KEY` = 'g-recaptcha-response'
- Error-code constants `E_INVALID_JSON` ... `E_CHALLENGE_TIMEOUT`
```

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

### setExpectedAction

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/ReCaptcha.md

Sets the expected action for v3 API verification.

```APIDOC
## setExpectedAction

### Description
Sets the expected action for v3 API verification. The value is compared case-insensitively to the `action` field of the siteverify response. Should be set per page.

### Method
setExpectedAction

### Signature
`public function setExpectedAction(string $action): self`

### Parameters
- **action** (string) - Required - Expected action.

### Return
`self` (current instance) for fluent chaining. Mutates in place.

### Usage Example
```php
$recaptcha = new ReCaptcha($secret);
$recaptcha->setExpectedAction('homepage');
```
```

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

### \ReCaptcha\ReCaptcha::setExpectedAction()

Source: https://github.com/google/recaptcha/blob/main/README.md

Sets the expected action for the v3 API. Returns the ReCaptcha instance for chaining.

```APIDOC
## \ReCaptcha\ReCaptcha::setExpectedAction()

### Description
Sets the expected action for the v3 API. Returns the `ReCaptcha` instance for chaining.

### Method
setExpectedAction

### Parameters
- **$action** (string) - Required - The expected action name.

### Request Example
```php
$recaptcha->setExpectedAction('homepage');
```

### Response
Returns the `ReCaptcha` instance for chaining.
```

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

### \ReCaptcha\ReCaptcha::verify()

Source: https://github.com/google/recaptcha/blob/main/README.md

Verifies the user's reCAPTCHA response with the reCAPTCHA service.

```APIDOC
## \ReCaptcha\ReCaptcha::verify()

### Description
Verifies the user's reCAPTCHA response with the reCAPTCHA service. Returns a response object that indicates success or failure.

### Method
verify

### Parameters
- **$response** (string) - Required - The reCAPTCHA response token (usually from `$_POST[\ReCaptcha\ReCaptcha::RESPONSE_KEY]` or from `grecaptcha.execute()`).
- **$remoteIp** (string) - Required - The user's IP address.

### Request Example
```php
$resp = $recaptcha->verify($gRecaptchaResponse, $remoteIp);
```

### Response
Returns a `ReCaptchaResponse` object. Use `isSuccess()` to check success and `getErrorCodes()` to retrieve error codes.

### Response Example
```php
if ($resp->isSuccess()) {
    // Verified!
} else {
    $errors = $resp->getErrorCodes();
}
```
```

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

### Response::fromJson

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/Response.md

Static factory method for creating a Response object from raw JSON.

```APIDOC
## Response::fromJson

### Description
Static factory that parses a raw JSON string (from the siteverify service or a transport's synthetic error payload) into a Response object. It never throws; all parse/reasoning failures are folded into error codes.

### Method
fromJson

### Signature
public static function fromJson(string $json): Response

### Parameters
- `json` (string) - Required - Raw JSON body returned by the siteverify service (or by a transport's synthetic error payload).

### Return
Response - never throws; all parse/reasoning failures are folded into error codes.

### Parsing Rules
1. `json_decode($json, true)`; if the result is not an `array` → `new Response(false, [ReCaptcha::E_INVALID_JSON])`.
2. Optional fields are extracted with type guards:
   - `hostname` — `['hostname']` if it is a `string`, else `''`
   - `challenge_ts` — `['challenge_ts']` if it is a `string`, else `''`
   - `apk_package_name` — `['apk_package_name']` if it is a `string`, else `''`
   - `score` — `floatval(['score'])` if it is numeric, else `null`
   - `action` — `['action']` if it is a `string`, else `''`
3. If `['success']` is `true` → `Response(true, [], hostname, challengeTs, apkPackageName, score, action)`.
4. Else if `['error-codes']` is an `array` → all `string`-typed entries are kept (`array_filter(..., 'is_string')` + `array_values`) → `Response(false, $errorCodes, ...)`.
5. Else → `Response(false, [ReCaptcha::E_UNKNOWN_ERROR], ...)`.

### Usage - Basic
```php
use ReCaptcha\Response;

$resp = Response::fromJson('{"success": true, "hostname": "recaptcha-demo.appspot.com", "challenge_ts": "2025-01-01T00:00:00Z", "score": 0.9, "action": "homepage"}');

if ($resp->isSuccess()) {
    $score = $resp->getScore(); // 0.9
}
```

### Usage - Error Handling
```php
use ReCaptcha\Response;
use ReCaptcha\ReCaptcha;

$resp = Response::fromJson('not-json-at-all');
if (!$resp->isSuccess()) {
    // error-codes contains exactly ['invalid-json']
    $codes = $resp->getErrorCodes();
} else {
    // unreachable for non-JSON input
}

$resp2 = Response::fromJson('{"success": false, "error-codes": ["invalid-input-response", "bad-request"]}');
if (!$resp2->isSuccess()) {
    $codes = $resp2->getErrorCodes(); // ['invalid-input-response', 'bad-request']
}
```
```

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

### Post::submit

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/RequestMethod-Post.md

Sends the verification request to the reCAPTCHA siteverify service using a PHP HTTP stream context and file_get_contents(). Returns the raw response body or a synthetic error JSON payload on failure.

```APIDOC
## Post::submit

### Description
Sends the verification request to the reCAPTCHA siteverify service using a PHP HTTP stream context and file_get_contents(). Returns the raw response body or a synthetic error JSON payload on failure.

### Method
submit

### Signature
```php
public function submit(RequestParameters $params): string
```

### Parameters
- **params** (RequestParameters) - Required - Request parameters; encoded to an `application/x-www-form-urlencoded` query string via `toQueryString()`.

### Return Value
- **string** - The raw body of the reCAPTCHA response (JSON), or a synthetic error JSON payload on failure.

### Behavior
1. Builds the stream context options:
   ```php
   $options = [
       'ssl' => [
           'verify_peer'      => true,
           'verify_peer_name' => true,
       ],
       'http' => [
           'header'         => "Content-type: application/x-www-form-urlencoded\r\n",
           'method'         => 'POST',
           'content'        => $params->toQueryString(),
           'timeout'        => $this->timeout,
           'ignore_errors'  => true,
       ],
   ];
   ```
2. `$context = stream_context_create($options);`
3. `$response = file_get_contents($this->siteVerifyUrl, false, $context);`
4. Inspects the captured response headers via `http_get_last_response_headers()`; if the first header line does not match `#^HTTP/\d+\.\d+\s+200\b#` (i.e. not a `200` status), returns the `bad-response` payload.

### Failure Conditions
| Condition | Returned payload |
|---|---|
| `file_get_contents()` does not return a `string` (e.g. connection failed, disabled URL access) | `{"success": false, "error-codes": ["connection-failed"]}` |
| First response header line is not an HTTP `200` status | `{"success": false, "error-codes": ["bad-response"]}` |

### Usage Example
```php
use ReCaptcha\ReCaptcha;
use ReCaptcha\RequestMethod\Post;

$recaptcha = new ReCaptcha($secret, new Post());
$resp = $recaptcha->verify($token, $remoteIp);
```

### Usage Example - Handling transport failures
```php
use ReCaptcha\ReCaptcha;
use ReCaptcha\RequestMethod\Post;

$recaptcha = new ReCaptcha($secret, new Post(ReCaptcha::SITE_VERIFY_URL_ALTERNATIVE, 30));
$resp = $recaptcha->verify($token);

if (!$resp->isSuccess()) {
    $codes = $resp->getErrorCodes();
    if (in_array(ReCaptcha::E_CONNECTION_FAILED, $codes)) {
        // General network failure or allow_url_open disabled —
        // consider ReCaptcha\RequestMethod\SocketPost instead.
    }
}
```
```

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

### Use immutable with*() methods for shared base instance

Source: https://github.com/google/recaptcha/blob/main/README.md

Immutable with*() methods return a cloned ReCaptcha instance, leaving the original unchanged. Use this pattern when sharing a base instance in a dependency injection container or persistent worker runtime.

```php
<?php
$baseRecaptcha = (new \ReCaptcha\ReCaptcha($secret))
    ->withExpectedHostname('recaptcha-demo.appspot.com')
    ->withChallengeTimeout(120);

$resp = $baseRecaptcha
    ->withExpectedAction('homepage')
    ->withScoreThreshold(0.5)
    ->verify($gRecaptchaResponse, $remoteIp);
```

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

### Basic CurlPost usage with verify

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/RequestMethod-CurlPost.md

Basic usage of CurlPost with the ReCaptcha client to verify a token.

```php
use ReCaptcha\ReCaptcha;
use ReCaptcha\RequestMethod\CurlPost;

$recaptcha = new ReCaptcha($secret, new CurlPost());
$resp = $recaptcha->verify($token, $remoteIp);
```

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

### withExpectedHostname method signature

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/ReCaptcha.md

Signature of the withExpectedHostname method. It returns a cloned ReCaptcha instance with the hostname set, leaving the original unmodified.

```php
public function withExpectedHostname(string $hostname): self
```

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

### setExpectedAction usage

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/ReCaptcha.md

Sets the expected action for v3 API verification. Mutates the instance and returns it for chaining.

```php
$recaptcha = new ReCaptcha($secret);
$recaptcha->setExpectedAction('homepage');
```

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

### getHostname method signature

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/Response.md

Returns the hostname of the site where the reCAPTCHA was solved. Used for hostname-mismatch check; useful to validate against an allowlist of multiple hostnames yourself after calling verify().

```php
public function getHostname(): string
```

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

### withExpectedAction usage

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/ReCaptcha.md

Immutable version of setExpectedAction. Clones the instance, applies the action, and returns the clone.

```php
$verifier = $baseRecaptcha->withExpectedAction('examples/v3strict');
```

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

### SocketPost::__construct

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/RequestMethod-SocketPost.md

Constructor for the SocketPost request method, which sends POST requests to the reCAPTCHA siteverify service over a raw TLS socket.

```APIDOC
## SocketPost::__construct

### Description
Creates a new SocketPost request method instance. It sends POST requests to the reCAPTCHA siteverify service over a raw TLS socket, useful when `allow_url_fopen` is disabled.

### Method
Constructor

### Signature
`public function __construct(?string $siteVerifyUrl = null, int $timeout = 60)`

### Parameters
- **siteVerifyUrl** (`?string`) - Optional - URL for the reCAPTCHA siteverify API. Defaults to `https://www.google.com/recaptcha/api/siteverify` when `null`.
- **timeout** (`int`) - Optional - Timeout in seconds for the socket connection and stream read. Defaults to `60`.

### Usage Example
```php
use ReCaptcha\ReCaptcha;
use ReCaptcha\RequestMethod\SocketPost;

$recaptcha = new ReCaptcha($secret, new SocketPost());
```
```

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

### Catch reCAPTCHA errors in PHP consumer code

Source: https://github.com/google/recaptcha/blob/main/_autodocs/errors.md

Shows how to handle errors in consumer code using the reCAPTCHA PHP library. Only construction throws a RuntimeException when the secret is empty; verification never throws. Inspect the Response object and use getErrorCodes() with match to handle specific error cases.

```php
use ReCaptcha\ReCaptcha;

// Construction-time failure (the only thrown error):
try {
    $recaptcha = new ReCaptcha($secret); // throws RuntimeException if $secret is ''
} catch (\RuntimeException $e) {
    error_log('reCAPTCHA misconfiguration: '.$e->getMessage());
}

// Verification-time failures never throw — always inspect the Response:
$resp = $recaptcha->verify($token, $remoteIp);

if ($resp->isSuccess()) {
    // pass
} else {
    foreach ($resp->getErrorCodes() as $code) {
        match ($code) {
            case ReCaptcha::E_CONNECTION_FAILED:  // case 3
            case ReCaptcha::E_BAD_RESPONSE:       // case 4/5
            case ReCaptcha::E_INVALID_JSON:       // case 6
            case ReCaptcha::E_UNKNOWN_ERROR:      // case 8
                // transport/parse-level problem — retry or alert
            case ReCaptcha::E_MISSING_INPUT_RESPONSE: // case 1
                // user submitted without solving — reload widget
            default:
                // service error codes and merged client codes 9-13
        }
    }
}
```

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

### setExpectedApkPackageName usage

Source: https://github.com/google/recaptcha/blob/main/_autodocs/api-reference/ReCaptcha.md

Sets the expected APK package name for Android app verification. Mutates the instance and returns it for chaining.

```php
$recaptcha = new ReCaptcha($secret);
$recaptcha->setExpectedApkPackageName('com.example.myapp');
```
Tokens:
Raw