doc/dev/plugins/form/vendor/google/recaptcha/ARCHITECTURE.md

Architecture

The general pattern of usage is to instantiate the ReCaptcha class with your secret key, specify any additional validation rules, and then call verify() with the reCAPTCHA response and user's IP address. For example:

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

By default, this will use the stream_context_create() and file_get_contents() to make a POST request to the reCAPTCHA service. This is handled by the RequestMethod\Post class.

Alternate request methods

You may need to use other methods for making requests in your environment. The ReCaptcha class allows an optional RequestMethod instance to configure this. For example, if you want to use cURL instead you can do this:

<?php
$recaptcha = new \ReCaptcha\ReCaptcha($secret, new \ReCaptcha\RequestMethod\CurlPost());

Alternatively, you can also use a socket:

<?php
$recaptcha = new \ReCaptcha\ReCaptcha($secret, new \ReCaptcha\RequestMethod\SocketPost());

Adding new request methods

Create a class that implements the RequestMethod interface. The convention is to name this class RequestMethod\MethodTypePost and create a separate RequestMethod\MethodType class that wraps just the calls to the network calls themselves. This means that the RequestMethod\MethodTypePost can be unit tested by passing in a mock. Take a look at RequestMethod\CurlPost and RequestMethod\Curl with the matching RequestMethod/CurlPostTest to see this pattern in action.

Error conventions

The client returns the response as provided by the reCAPTCHA services augmented with additional error codes based on the client's checks. When adding a new RequestMethod ensure that it returns the ReCaptcha::E_CONNECTION_FAILED and ReCaptcha::E_BAD_RESPONSE where appropriate.