PHPackages                             gkcaptcha/gkcaptcha-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. gkcaptcha/gkcaptcha-php

ActiveLibrary

gkcaptcha/gkcaptcha-php
=======================

PHP SDK for gkCAPTCHA token verification. Zero Composer runtime dependencies.

v0.1.0(1mo ago)001MITPHPPHP >=8.1

Since Mar 26Pushed 1mo agoCompare

[ Source](https://github.com/gatekeepersa/gkcaptcha-php)[ Packagist](https://packagist.org/packages/gkcaptcha/gkcaptcha-php)[ Docs](https://gatekeeper.sa)[ RSS](/packages/gkcaptcha-gkcaptcha-php/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (1)Versions (2)Used By (1)

gkcaptcha-php
=============

[](#gkcaptcha-php)

PHP SDK for [gkCAPTCHA](https://gatekeeper.sa) token verification.

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

---

Quick Start
-----------

[](#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
------------

[](#installation)

```
composer require gkcaptcha/gkcaptcha-php
```

---

HTTP Transport
--------------

[](#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
----------------------

[](#constructor-parameters)

ParameterTypeDefaultDescription`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
-----------------------

[](#fail-open--fail-closed)

### Default: Fail-Open

[](#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

[](#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()
-------------

[](#verifytoken)

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

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

VerifyTokenResponse Properties
------------------------------

[](#verifytokenresponse-properties)

PropertyTypeDescription`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
-----------

[](#error-codes)

CodeWhen 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
----------------------

[](#reasoncode-enum-values)

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

ValueMeaning`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
-------------------

[](#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
-------

[](#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
-------

[](#license)

MIT — see [LICENSE](LICENSE).

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance90

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity32

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

47d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/270917593?v=4)[GateKeeper](/maintainers/gatekeepersa)[@gatekeepersa](https://github.com/gatekeepersa)

---

Top Contributors

[![abdulr7mann](https://avatars.githubusercontent.com/u/51442494?v=4)](https://github.com/abdulr7mann "abdulr7mann (1 commits)")

---

Tags

captchagatekeeperverificationbot-protection

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/gkcaptcha-gkcaptcha-php/health.svg)

```
[![Health](https://phpackages.com/badges/gkcaptcha-gkcaptcha-php/health.svg)](https://phpackages.com/packages/gkcaptcha-gkcaptcha-php)
```

###  Alternatives

[google/recaptcha

Client library for reCAPTCHA, a free service that protects websites from spam and abuse.

3.6k89.1M222](/packages/google-recaptcha)[s1syphos/php-simple-captcha

Simple captcha generator

2737.8k6](/packages/s1syphos-php-simple-captcha)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)