PHPackages                             gkcaptcha/gkcaptcha-laravel - 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. [Validation & Sanitization](/categories/validation)
4. /
5. gkcaptcha/gkcaptcha-laravel

ActiveLibrary[Validation & Sanitization](/categories/validation)

gkcaptcha/gkcaptcha-laravel
===========================

Laravel integration for gkCAPTCHA: middleware, validation rule, Blade directive, and service provider

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

Since Mar 26Pushed 1mo agoCompare

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

READMEChangelogDependencies (4)Versions (2)Used By (0)

gkcaptcha-laravel
=================

[](#gkcaptcha-laravel)

Laravel integration package for [gkCAPTCHA](https://gatekeeper.sa). Provides a service provider, middleware, validation rule, Blade directive, and Facade for CAPTCHA protection with a single line of configuration.

Requirements
------------

[](#requirements)

- PHP 8.1+
- Laravel 10 or 11
- `gkcaptcha/gkcaptcha-php` ^1.0 (included as a dependency)

Installation
------------

[](#installation)

```
composer require gkcaptcha/gkcaptcha-laravel
```

The package auto-discovers via Laravel's package auto-discovery. No manual registration required.

Configuration
-------------

[](#configuration)

Publish the config file:

```
php artisan vendor:publish --tag=gkcaptcha-config
```

Add to `.env`:

```
GKCAPTCHA_SECRET_KEY=sk_live_your_secret_key
GKCAPTCHA_SITE_KEY=pk_live_your_site_key
GKCAPTCHA_API_URL=https://gkcaptcha.gatekeeper.sa
GKCAPTCHA_TIMEOUT=5
GKCAPTCHA_FAIL_CLOSED=false
GKCAPTCHA_WIDGET_URL=https://gkcaptcha.gatekeeper.sa/widget/gk-captcha.js
```

### Environment Variables

[](#environment-variables)

VariableDefaultDescription`GKCAPTCHA_SECRET_KEY`*(required)*Server-side secret key for token verification`GKCAPTCHA_SITE_KEY`*(required)*Public site key for the widget`GKCAPTCHA_API_URL``https://gkcaptcha.gatekeeper.sa`gkCAPTCHA API base URL`GKCAPTCHA_TIMEOUT``5.0`Request timeout in seconds`GKCAPTCHA_FAIL_CLOSED``false`Block requests on network error (fail-closed)`GKCAPTCHA_WIDGET_URL``https://gkcaptcha.gatekeeper.sa/widget/gk-captcha.js`Widget script URLBlade Directive
---------------

[](#blade-directive)

Add the CAPTCHA widget to any Blade template:

```

    @csrf

    @gkcaptcha('pk_live_your_site_key')

    Submit

```

If `GKCAPTCHA_SITE_KEY` is set in `.env`, you can omit the argument:

```
@gkcaptcha
```

The directive outputs:

```

```

Middleware
----------

[](#middleware)

### Route Group (recommended)

[](#route-group-recommended)

Protect a group of routes by adding `VerifyCaptcha` to a route group:

```
use GkCaptcha\Laravel\Http\Middleware\VerifyCaptcha;

Route::middleware([VerifyCaptcha::class])->group(function () {
    Route::post('/contact', [ContactController::class, 'store']);
    Route::post('/register', [RegisterController::class, 'store']);
});
```

### Global Kernel Registration (Laravel 10)

[](#global-kernel-registration-laravel-10)

In `app/Http/Kernel.php`:

```
protected $routeMiddleware = [
    // ...
    'captcha' => \GkCaptcha\Laravel\Http\Middleware\VerifyCaptcha::class,
];
```

Then use the alias:

```
Route::post('/contact', [ContactController::class, 'store'])->middleware('captcha');
```

### Token Sources

[](#token-sources)

The middleware reads the CAPTCHA token from (in priority order):

1. `captchaToken` body field (form POST or JSON body)
2. `X-Captcha-Token` request header (AJAX / API)

### Middleware Responses

[](#middleware-responses)

ConditionHTTP StatusBodyNo token present403`{"success": false, "error": "CAPTCHA token required"}`Token invalid403`{"success": false, "error": "CAPTCHA verification failed"}`Network error (fail-open)passes throughWarning logged, request continuesToken validpasses throughNormal route responseValidation Rule
---------------

[](#validation-rule)

Use the `gkcaptcha` rule in form request classes or inline validators:

```
// In a FormRequest class:
public function rules(): array
{
    return [
        'email'        => 'required|email',
        'captchaToken' => 'required|gkcaptcha',
    ];
}
```

Or with the Rule object directly:

```
use GkCaptcha\Laravel\Rules\GkCaptchaRule;
use GkCaptcha\GkCaptchaClient;

$rules = [
    'captchaToken' => ['required', new GkCaptchaRule(app(GkCaptchaClient::class))],
];

$validator = Validator::make($request->all(), $rules);
```

Facade
------

[](#facade)

For inline verification anywhere in your application:

```
use GkCaptcha\Laravel\Facades\GkCaptcha;

$result = GkCaptcha::verifyToken(
    token:     $request->input('captchaToken'),
    clientIP:  $request->ip(),
    userAgent: $request->userAgent(),
);

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

Fail-Open Behavior
------------------

[](#fail-open-behavior)

By default (`GKCAPTCHA_FAIL_CLOSED=false`), network errors when reaching the gkCAPTCHA API allow the request to proceed. A warning is logged:

```
[warning] gkCAPTCHA API unreachable, failing open {"error": "..."}

```

This prevents gkCAPTCHA API availability from causing downtime on your application.

Set `GKCAPTCHA_FAIL_CLOSED=true` to block requests when the API is unreachable. This is appropriate for high-security environments where it is better to reject users than to risk allowing bots through.

Testing
-------

[](#testing)

The package includes PHPUnit-compatible tests using Orchestra Testbench.

With dependencies installed:

```
cd sdks/laravel
composer install
./vendor/bin/phpunit tests/
```

For environments without Composer (CI, Docker images without Testbench), a standalone runner is included:

```
php tests/run_tests.php
```

License
-------

[](#license)

MIT

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance90

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

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

middlewarelaravelvalidationcaptchagkcaptcha

###  Code Quality

TestsPHPUnit

### Embed Badge

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

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

###  Alternatives

[proengsoft/laravel-jsvalidation

Validate forms transparently with Javascript reusing your Laravel Validation Rules, Messages, and FormRequest

1.1k2.3M49](/packages/proengsoft-laravel-jsvalidation)[axlon/laravel-postal-code-validation

Worldwide postal code validation for Laravel and Lumen

3853.3M1](/packages/axlon-laravel-postal-code-validation)[laravel-validation-rules/credit-card

Validate credit card number, expiration date, cvc

2412.2M5](/packages/laravel-validation-rules-credit-card)[illuminatech/validation-composite

Allows uniting several validation rules into a single one for easy re-usage

184485.5k](/packages/illuminatech-validation-composite)[galahad/laravel-addressing

Laravel package providing addressing functionality

70316.6k](/packages/galahad-laravel-addressing)[johnpaulmedina/laravel-usps

USPS Addresses API v3 (OAuth2) for Laravel

2622.6k](/packages/johnpaulmedina-laravel-usps)

PHPackages © 2026

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