README

PHP SDK for gkCAPTCHA token verification.

Zero Composer runtime dependencies — only php >=8.1 required.

Quick Start

use GkCaptcha\GkCaptchaClient;

$client = new GkCaptchaClient(
    secretKey: $_ENV['GKCAPTCHA_SECRET_KEY'],
    siteKey:   $_ENV['GKCAPTCHA_SITE_KEY'],
);

$result = $client->verifyToken($request->input('captchaToken'));

if (!$result->success) {
    return response()->json(['error' => 'CAPTCHA verification failed'], 403);
}

Installation

composer require gkcaptcha/gkcaptcha-php

HTTP Transport

• Primary: curl extension (enabled by default on all PHP 8.1 hosts).
• Fallback: file_get_contents() with a stream context, used only when curl is unavailable.

No Guzzle, no PSR-18, no additional Composer packages required.

Constructor Parameters

All string parameters can be omitted and resolved from environment variables.

Fail-Open / Fail-Closed

Default: Fail-Open

If the Gatekeeper API is unreachable (network error, timeout) after all retries, the client returns a successful response with failOpen=true — the request passes through.

$result = $client->verifyToken($token);

if ($result->failOpen) {
    // Network error — request allowed through (fail-open policy)
    // Log a warning, monitor for sustained failures
}

This is the industry-standard default (used by reCAPTCHA and hCaptcha). It protects legitimate users during API outages.

Fail-Closed Mode

To block requests on network failure, set failClosed: true:

$client = new GkCaptchaClient(
    secretKey:  $_ENV['GKCAPTCHA_SECRET_KEY'],
    siteKey:    $_ENV['GKCAPTCHA_SITE_KEY'],
    failClosed: true,
);

try {
    $result = $client->verifyToken($token);
} catch (\GkCaptcha\GkCaptchaException $e) {
    // Network error — request blocked (fail-closed policy)
    return response()->json(['error' => 'Verification unavailable'], 503);
}

verifyToken()

public function verifyToken(
    string $token,
    ?string $clientIP  = null,
    ?string $userAgent = null,
): VerifyTokenResponse

VerifyTokenResponse Properties

Error Codes

Only thrown as GkCaptchaException with failClosed=true for NETWORK_ERROR. INVALID_CONFIG always throws regardless of failClosed.

ReasonCode Enum Values

VerifyTokenResponse::$reasonCode contains one of these strings on failure:

Use the ReasonCode enum for type-safe comparisons:

use GkCaptcha\ReasonCode;

if ($result->reasonCode === ReasonCode::TokenExpired->value) {
    // Handle expired token
}

Laravel Quick Start

// In a form request or controller:
use GkCaptcha\GkCaptchaClient;

$client = new GkCaptchaClient(
    secretKey: config('services.gatekeeper.secret'),
    siteKey:   config('services.gatekeeper.site_key'),
);

$result = $client->verifyToken($request->captchaToken, $request->ip(), $request->userAgent());

if (!$result->success) {
    abort(403, 'CAPTCHA verification failed');
}

Testing

# Install dev dependencies (phpunit/phpunit ^10)
composer install

# Run tests (requires php-dom, php-mbstring, php-xml extensions)
./vendor/bin/phpunit tests/

# Alternative: run standalone test runner (no extension requirements)
php tests/run_tests.php

License

MIT — see LICENSE.