gkcaptcha-php

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.