recaptcha

To add a new request method for communicating with the reCAPTCHA service, create a class that implements the ReCaptcha\RequestMethod interface. Following the project convention, name the class RequestMethod\_MethodType_Post (for example, RequestMethod\CurlPost). When implementing a new method, ensure it returns the following error codes where appropriate:

• ReCaptcha::E_CONNECTION_FAILED
• ReCaptcha::E_BAD_RESPONSE

To verify a user's reCAPTCHA response on the server side, instantiate the \ReCaptcha\ReCaptcha class with your secret key and call the verify() method.

verify() requires the reCAPTCHA response token (often found in $_POST or sent from JS) and the user's remote IP address. You can chain configuration methods to enforce specific validation rules before calling verify().

<?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();
}

To verify a reCAPTCHA response, instantiate the ReCaptcha\ReCaptcha class with your secret key. You can optionally chain methods like setExpectedHostname() to apply additional validation rules. Call verify() passing the reCAPTCHA response and the user's remote IP address. The method returns a response object that can be checked for success using isSuccess() or for errors using getErrorCodes().

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

You can install the library using Composer (recommended) or via direct download.

Using Composer

Run the following command in your project directory:

composer require google/recaptcha "^1.5"

Alternatively, add this to your composer.json:

"require": {
    "google/recaptcha": "^1.5"
}

Direct Download

1. Download the ZIP file from the repository.
2. Extract it into your project.
3. Require the provided autoloader script:

require_once '/path/to/recaptcha/src/autoload.php';

Note on PHP Versions: This library requires PHP 8 or higher. For earlier versions of PHP, you must use the 1.2 releases.

You can run the included examples locally using the built-in PHP development server via Composer:

composer run-script serve-examples

Once running, the examples will be available at http://localhost:8080/.

The \ReCaptcha\ReCaptcha class provides several setter methods to enforce validation. These methods return the instance, allowing for method chaining.

• setExpectedHostname($hostname): Ensures the hostname matches. Use this if you have disabled "Domain/Package Name Validation" for your credentials. To validate against multiple hostnames, call verify() and then check $resp->getHostname() against your allowed list.
• setExpectedApkPackageName($apkPackageName): Used for verifying responses from Android apps (requires disabling "Domain/Package Name Validation").
• setExpectedAction($action): Ensures the action matches (required for reCAPTCHA v3).
• setScoreThreshold($threshold): Sets a score threshold for reCAPTCHA v3 responses.
• setChallengeTimeout($timeoutSeconds): Sets a timeout between the user passing the challenge and the server processing it.

By default, the library attempts to use cURL (\ReCaptcha\RequestMethod\CurlPost). If cURL is unavailable, it falls back to file_get_contents() via \ReCaptcha\RequestMethod\Post.

You can explicitly specify a request method by passing a RequestMethod instance to the ReCaptcha constructor.

Available methods include:

• \ReCaptcha\RequestMethod\CurlPost: Forces the use of cURL.
• \ReCaptcha\RequestMethod\Post: Uses file_get_contents() and stream_context_create().
• \ReCaptcha\RequestMethod\SocketPost: Uses a socket connection.

The ReCaptcha client allows you to enforce additional validation rules during the verify() call using a fluent interface. These checks are performed locally after receiving the API response.

• setExpectedHostname(string $hostname): Ensures the response hostname matches (e.g., www.google.com).
• setExpectedApkPackageName(string $apkPackageName): Ensures the APK package name matches for mobile integrations.
• setExpectedAction(string $action): Ensures the reCAPTCHA action matches the expected action for the current page.
• setScoreThreshold(float $threshold): Ensures the reCAPTCHA score is greater than or equal to the provided float (between 0 and 1).
• setChallengeTimeout(int $timeoutSeconds): Ensures the time elapsed since the challenge timestamp does not exceed the specified seconds.