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

Parameter	Type	Default	Description
`secretKey`	string	`''`	Your Gatekeeper secret key. Env: `GKCAPTCHA_SECRET_KEY`
`siteKey`	string	`''`	Your Gatekeeper site key. Env: `GKCAPTCHA_SITE_KEY`
`apiUrl`	string	`https://gkcaptcha.gatekeeper.sa`	Override API base URL. Env: `GKCAPTCHA_API_URL`
`timeout`	float	`5.0`	HTTP request timeout in seconds.
`maxRetries`	int	`1`	Number of retries on network error.
`retryDelay`	float	`1.0`	Delay between retries in seconds.
`failClosed`	bool	`false`	See Fail-Open / Fail-Closed below.

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

Parameter	Description
`token`	The token from the `captcha-verified` CustomEvent.
`clientIP`	Optional client IP for binding verification.
`userAgent`	Optional User-Agent for binding verification.

VerifyTokenResponse Properties

Property	Type	Description
`success`	`bool`	`true` if verification passed.
`score`	`float`	Risk score 0.0 (human) – 1.0 (bot).
`timestamp`	`int`	Unix timestamp when the token was issued.
`error`	`?string`	Human-readable error message on failure.
`reasonCode`	`?string`	Machine-readable reason code on failure.
`failOpen`	`bool`	`true` when success was returned due to fail-open policy.

Error Codes

Code	When thrown
`INVALID_CONFIG`	`secretKey` or `siteKey` empty after env var resolution.
`NETWORK_ERROR`	HTTP transport failure (curl error, timeout).

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:

Value	Meaning
`missing_token`	Token field was empty in the request.
`invalid_site_key`	Site key not found.
`invalid_secret`	Secret key does not match.
`site_disabled`	Site has been disabled.
`invalid_signature`	Token signature verification failed.
`token_expired`	Token has exceeded its TTL.
`site_key_mismatch`	Token was issued for a different site key.
`token_already_used`	Token has already been consumed.
`binding_mismatch`	IP or User-Agent does not match the token.
`internal_error`	Unexpected server-side error.

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.

gkcaptcha/gkcaptcha-php

包简介

关键字：

README 文档