PHP¶

For PHP, there are two packages. Both verify the token on the server and give the same result object.

Select the package¶

Select the package for the PHP version of your application:

Package	PHP	Technology
`myra-security-gmbh/eu-captcha`	From version 8.0	Named arguments, type declarations, HTTP with Guzzle (`guzzlehttp/guzzle` ^6.0 or ^7.0)
`myra-security-gmbh/eu-captcha-old`	From version 5.0	No other dependencies, HTTP with `file_get_contents()` and a stream context

Requirements¶

The following requirements must be met:

Requirement	Value
PHP	From version 8.0 for `eu-captcha`, from version 5.0 for `eu-captcha-old`
Composer	Access to the command line of the server
Credentials	Public sitekey and secret from the Details view

Install the package¶

Install the package for PHP 8:

composer require myra-security-gmbh/eu-captcha

For PHP 5 to PHP 7, install this package instead:

composer require myra-security-gmbh/eu-captcha-old

Add the script link to each page that has a form to protect:

<script src="https://cdn.eu-captcha.eu/verify.js" async defer></script>

Add the widget to the form:

<div class="eu-captcha" data-sitekey="EUCAPTCHA_SITE_KEY"></div>

Note

In a single-page application with React, Vue, or Angular, embed the widget with the applicable npm package. Then the PHP package does only the verification on the server.

Verify the token¶

Verify the transmitted token on the server:

<?php

use Myrasec\EuCaptcha;

$captcha = new EuCaptcha(
    sitekey: EUCAPTCHA_SITE_KEY,
    secret:  EUCAPTCHA_SECRET_KEY,
);

$result = $captcha->validate();

if (!$result->success()) {
    // Reject the form submission
}

With eu-captcha-old, give the values as an associative array instead:

<?php

use Myrasec\EuCaptcha;

$captcha = new EuCaptcha([
    'sitekey' => EUCAPTCHA_SITE_KEY,
    'secret'  => EUCAPTCHA_SECRET_KEY,
]);

$result = $captcha->validate();

validate() reads the token from $_POST['eu-captcha-response']. If $_POST is empty, the method reads the body of the request as JSON. The method gets the IP address of the visitor from the headers of the request.

Options¶

These options are available:

Option	Type	Default	Effect
`sitekey`	string	—	Public sitekey. The value is necessary.
`secret`	string	—	Secret key. The value is necessary and must not occur in the browser.
`failDefault`	bool	`true`	Return value for the network condition and the token condition when the API is not available. `true` permits the transmission, `false` rejects it.
`checkCdnHeaders`	bool	`true`	Gets the IP address of the visitor from the `HTTP_CLIENT_IP`, `HTTP_X_FORWARDED_FOR`, and `HTTP_X_REAL_IP` headers before `REMOTE_ADDR` is used. Set the value to `false` if the server is not behind an upstream system, or if you give the IP address yourself.

Only eu-captcha for PHP 8 has these additional options:

Option	Type	Default	Effect
`verifyUrl`	string	Address of the production environment	Overwrites the address of the `/verify` endpoint. Use the option for tests.
`credentialsUrl`	string	Address of the production environment	Overwrites the address of the `/verify-credentials` endpoint.
`client`	`?Client`	`null`	Your own instance of Guzzle for different settings or for tests.

The result object¶

validate() gives an EuCaptchaResult object with three methods:

Method	Gives `true` when
`success()`	the API was available and the token is valid.
`successNetwork()`	the call of the API completed without a network error or a transmission error.
`successToken()`	the API reported the transmitted token as valid.

The separate query tells a failed challenge from a malfunction of the API:

<?php

$result = $captcha->validate();

if (!$result->successNetwork()) {
    // Could not reach the API — consider logging or alerting
}

if (!$result->successToken()) {
    // Token was rejected — the submission is likely automated
}

Give the token and the IP address yourself¶

For different field names, give the token and the IP address yourself:

<?php

$token    = $_POST['my-captcha-field'] ?? '';
$clientIp = $_SERVER['REMOTE_ADDR'];

$result = $captcha->validate($token, $clientIp);

Verify the credentials¶

With verifyCredentials(), you verify the sitekey and the secret without a token from the browser, for example at the start of the application:

<?php

$captcha = new EuCaptcha(sitekey: EUCAPTCHA_SITE_KEY, secret: EUCAPTCHA_SECRET_KEY);

if (!$captcha->verifyCredentials()) {
    // Credentials are invalid or the API is unreachable — log and alert
}

For a network error or an API error, the method gives false and causes no exception. Thus, the call is also safe during the initialization.

See Verify the sitekey and the secret.

Symfony and Laravel¶

For the two frameworks, see Symfony and Laravel.

Full example¶

See React and PHP.