README

A PHP client for the Friendly Captcha service. This client makes it easy to connect to the Friendly Captcha API for captcha verification or Risk Intelligence retrieval.

Note, this is for Friendly Captcha v2 only.

Installation

Requires PHP 7.1 or later.

Install using Composer

composer require friendlycaptcha/sdk

Usage

Below are some basic examples that demonstrate how to use this SDK.

For complete examples, take a look at the examples directory.

Initialization

use FriendlyCaptcha\SDK\{Client, ClientConfig}

$config = new ClientConfig();
$config->setAPIKey("<YOUR API KEY>")->setSitekey("<YOUR SITEKEY (optional)>");

// You can also specify which endpoint to use, for example `"global"` or `"eu"`.
// $config->setApiEndpoint("eu")

$captchaClient = new Client($config)

Verifying a Captcha Response

function handleLoginRequest() {
    global $captchaClient;

    $captchaResponse = isset($_POST["frc-captcha-response"]) ? $_POST["frc-captcha-response"] : null;
    $result = $captchaClient->verifyCaptchaResponse($captchaResponse);

    if (!$result->wasAbleToVerify()) {
        if ($result->isClientError()) {
            // ALERT: your website is NOT PROTECTED because of a configuration error.
            // Send an alert to yourself, check your API key (and sitekey).
            error_log("Failed to verify captcha response because of configuration problem: " . print_r($result->getResponseError()));
        } else {
            // Something else went wrong, maybe there is a connection problem or the API is down.
            error_log("Failed to verify captcha response: " . print_r($result->getErrorCode()));
        }
    }

    if ($result->shouldReject()) {
        // The captcha was not OK, show an error message to the user
        echo "Captcha anti-robot check failed, please try again.";
        return;
    }

    // The captcha is accepted, handle the request:
    loginUser($_POST["username"], $_POST["password"]);
}

Retrieving Risk Intelligence

You can retrieve Risk Intelligence data using a token. This data provides detailed information about the risk profile of a request, including network data, geolocation, browser details, and risk scores.

function getRiskIntelligence() {
    global $frcClient;

    $token = isset($_POST["frc-risk-intelligence-token"]) ? $_POST["frc-risk-intelligence-token"] : null;
    $result = $frcClient->retrieveRiskIntelligence($token);

    if ($result->wasAbleToRetrieve()) {
        // Risk Intelligence token is valid and data was retrieved successfully.
        if ($result->isValid()) {
            // Token was invalid or expired. 
            $response = $result->getResponse();
            echo "Risk Intelligence data", $response->data;
        } else {
            $error = $result->getResponseError();
            error_log("Error:", $error);
        }
    } else {
        // Network issue or configuration problem.
        if ($result->isClientError()) {
            error_log("Configuration error - check your API key");
        } else {
            error_log("Network issue or service temporarily unavailable");
        }
    }
}

Development

Make sure you have PHP installed (e.g. with brew install php on a Macbook).

Install Composer

mkdir -p bin
php -r "copy('https://getcomposer.org/installer', './bin/composer-setup.php');"
# You can omit `--2.2 LTS` if you are using a more recent PHP version than 7.2
php bin/composer-setup.php --install-dir=bin --2.2 LTS

Install dependencies

bin/composer.phar install

Run the tests

First download the friendly-captcha-sdk-testserver for your operating system.

# Run the friendly-captcha-sdk-testserver
./friendly-captcha-sdk-testserver serve

Then open a new terminal, and run the following

# Generate the autoload files
./bin/composer.phar dump
./vendor/bin/phpunit

You should then see output like the following

PHPUnit 7.0.0 by Sebastian Bergmann and contributors.

............................                                      28 / 28 (100%)

Time: 36 ms, Memory: 4.00 MB

OK (28 tests, 110 assertions)

Optional

To make sure that the SDK is backwards compatible, make sure the tests pass in PHP 7.1. We recommend using Docker.

$ docker run --rm -it --network host -v $PWD:/php -w /php php:7.1-alpine /bin/sh
/php # apk update && apk add git

Then follow the steps above starting with Install Composer. You can run ./friendly-captcha-sdk-testserver serve outside the Docker container.

Some features you can't use to be compatible with PHP 7.1

• Typings of class member variables.
• Union types (outside of comments).

License

Open source under MIT. Contributions are welcome!