Laravel Integration

Laravel integration patterns with service provider, middleware, validation rule, Blade directive, and Facade.

Copy these patterns into your project to integrate gkCAPTCHA server-side verification.

Installation

terminal

composer require gkcaptcha/gkcaptcha-laravel

Requires PHP 8.1+ and Laravel 10 or 11. Auto-discovers via Laravel package auto-discovery.

Configuration

Publish the config file:

terminal

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

Add to your .env file:

.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

Blade Directive

Add the CAPTCHA widget to any Blade template with the @gkcaptcha directive:

contact.blade.php

<form method="POST" action="/contact">
    @csrf
    <input type="text" name="email" />

    @gkcaptcha

    <button type="submit">Submit</button>
</form>

form.blade.php

{{-- Pass site key explicitly --}}
@gkcaptcha('pk_live_your_site_key')

Middleware

Route Group

routes/web.php

use GkCaptcha\Laravel\Http\Middleware\VerifyCaptcha;

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

Kernel Alias (Laravel 10)

Kernel.php

// app/Http/Kernel.php (Laravel 10)
protected $routeMiddleware = [
    // ...
    'captcha' => \GkCaptcha\Laravel\Http\Middleware\VerifyCaptcha::class,
];

// Then use the alias:
Route::post('/contact', [ContactController::class, 'store'])->middleware('captcha');

Validation Rule

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

ContactRequest.php

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

Rule Object

Controller.php

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

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

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

Facade

Controller.php

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');
}

Error Handling

By default (GKCAPTCHA_FAIL_CLOSED=false), network errors when reaching the gkCAPTCHA API allow the request to proceed. A warning is logged. This prevents API availability from causing downtime on your application.

افتراضيًا، أخطاء الشبكة عند الاتصال بواجهة gkCAPTCHA تسمح بمرور الطلب مع تسجيل تحذير. لحظر الطلبات عند فشل الاتصال، اضبط GKCAPTCHA_FAIL_CLOSED=true.

Environment Variables

Variable	Required	Description
GKCAPTCHA_SECRET_KEY	Yes	Server-side secret key for token verification
GKCAPTCHA_SITE_KEY	Yes	Public site key for the widget
GKCAPTCHA_API_URL	No	API base URL (default: https://gkcaptcha.gatekeeper.sa)
GKCAPTCHA_TIMEOUT	No	Request timeout in seconds (default: 5)
GKCAPTCHA_FAIL_CLOSED	No	Block requests on network error (default: false)
GKCAPTCHA_WIDGET_URL	No	Widget script URL for Blade directive