Skip to content

PHP Module

The myra-security-gmbh/eu-captcha package is the official PHP client for server-side token verification. It wraps the verification API with automatic IP detection, configurable fault-tolerance, and a result object that exposes both network and token states separately.

Installation

composer require myra-security-gmbh/eu-captcha

Basic usage

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

// proceed with form processing

Replace EUCAPTCHA_SITE_KEY and EUCAPTCHA_SECRET_KEY with the values from your sitekey configuration. Store them in environment variables — do not hardcode them.

validate() reads the token automatically from $_POST['eu-captcha-response'] and resolves the client IP from CDN/proxy headers, so no extra wiring is needed in the common case.

validate() method

<?php

$result = $captcha->validate(?string $token = null, string $remoteAddr = '');

Both parameters are optional:

Parameter Type Description
$token string\|null The value of the eu-captcha-response POST field. When null, the method reads $_POST['eu-captcha-response'] automatically.
$remoteAddr string The visitor's IP address. When empty, the method resolves it automatically via checkCdnHeaders.

Pass the token and IP explicitly when you need full control (e.g. non-standard field names):

<?php

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

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

Configuration reference

All options are passed as named constructor arguments:

Option Type Default Description
sitekey string — Required. Your public sitekey.
secret string — Required. Your secret key. Never expose this client-side.
failDefault bool true Return value when the verification API cannot be reached. true = accept on network failure; false = reject.
checkCdnHeaders bool true When true, the client IP is resolved from HTTP_CLIENT_IP, HTTP_X_FORWARDED_FOR (first entry), and HTTP_X_REAL_IP before falling back to REMOTE_ADDR. Set to false when not behind a proxy, or when you always pass $remoteAddr explicitly.
verifyUrl string (production) Override the verification endpoint. Useful for testing.
credentialsUrl string (production) Override the verify-credentials endpoint.
client ?Client null Optional Guzzle client instance for custom configuration or testing.

Result object

validate() returns a Myrasec\EuCaptchaResult with three methods:

Method Returns Description
success() bool true if both the network call and token verification succeeded
successNetwork() bool true if the API was reachable and returned a response
successToken() bool true if the token itself passed verification

Use successNetwork() and successToken() individually when you need to distinguish between a network failure and a genuinely invalid token:

<?php

$result = $captcha->validate();

if (!$result->successNetwork()) {
    // API unreachable — decide whether to fail open or closed
} elseif (!$result->successToken()) {
    // Token invalid or already used
}

Fault tolerance

By default (failDefault: true) the client fails open: if the verification API is unreachable, success() returns true and the submission is accepted. This avoids locking out legitimate users during transient network issues.

Set failDefault to false for endpoints where you prefer to reject submissions when the API cannot be reached:

<?php

$captcha = new EuCaptcha(
    sitekey:     'EUCAPTCHA_SITE_KEY',
    secret:      'EUCAPTCHA_SECRET_KEY',
    failDefault: false,  // reject on network failure
);

Choose the right trade-off for your use case:

Scenario Recommended setting
Contact / signup forms — prefer availability failDefault: true (default)
High-security endpoints — prefer strictness failDefault: false

Verifying credentials

Use verifyCredentials() to confirm your sitekey and secret are valid without submitting a client token. This is useful for startup or configuration checks:

<?php

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

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

verifyCredentials() returns false on any network or API error rather than throwing.

Symfony usage

See the dedicated Symfony integration guide for service configuration, autowiring, and a controller example.

Laravel usage

See the dedicated Laravel integration guide for configuration, a controller example, and a Form Request pattern.