README

A Laravel wrapper for Cap — the self-hosted, privacy-friendly CAPTCHA alternative based on Proof-of-Work.

Cap works without tracking, cookies, or third-party services. This package integrates server-side token verification into Laravel through a service, a facade, a middleware, a validation rule, and Blade directives.

Requirements

• PHP ^8.2
• Laravel 11 or 12
• A running Cap instance (self-hosted via Docker)

Installation

composer require oliweb/laravel-cap

The service provider and facade are registered automatically via Laravel's package auto-discovery.

Publish the configuration file:

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

Publish the JS and CSS assets (required for @capScripts and @capStyles):

php artisan vendor:publish --tag=cap-assets

Publish the translation files (optional — to override messages):

php artisan vendor:publish --tag=cap-lang

Configuration

Add the following variables to your .env file:

CAP_ENDPOINT=https://cap.example.com/your-site-key/
CAP_SECRET=your-secret-key
CAP_TOKEN_FIELD=cap-token
CAP_TIMEOUT=5
CAP_FAIL_OPEN=false

Fail-open mode

By default, any communication error with the Cap instance (network failure, timeout, HTTP 5xx) blocks the request, just like an invalid token would.

Setting CAP_FAIL_OPEN=true inverts this: communication errors silently pass, so a Cap outage does not take your forms down with it.

An explicitly invalid token (success: false) is always rejected regardless of this setting. Fail-open only covers infrastructure failures, not verification failures.

Translations

Server-side messages (validation rule, middleware) are translatable. English and French are included out of the box.

To override or add a language, publish the translation files and edit lang/vendor/cap/{locale}/messages.php:

php artisan vendor:publish --tag=cap-lang

// lang/vendor/cap/fr/messages.php
return [
    'validation_failed' => 'La vérification :attribute a échoué. Veuillez réessayer.',
    'middleware_failed'  => 'La vérification Cap a échoué.',
];

Laravel selects the right file automatically based on App::getLocale().

Widget styling

Publish the CSS asset and include it via @capStyles:

php artisan vendor:publish --tag=cap-assets

Edit public/vendor/cap/cap-widget.css to override the CSS custom properties exposed by the widget:

cap-widget {
    --cap-color-primary:    #6366f1;
    --cap-color-success:    #22c55e;
    --cap-border-radius:    0.5rem;
    --cap-font-family:      inherit;
    /* ... */
}

Usage

Blade directives

Include the Cap widget and its script in any Blade form:

@capStyles
@capScripts

<form method="POST" action="/contact">
    @csrf
    @cap
    <button type="submit">Submit</button>
</form>

The widget automatically injects a hidden cap-token field into its parent form upon successful verification.

CSP nonce support

Both directives accept an optional nonce for strict Content Security Policies:

{{-- Laravel Vite --}}
@capScripts(Vite::cspNonce())
@cap(Vite::cspNonce())

{{-- Spatie CSP or custom nonce --}}
@capScripts($nonce)
@cap($nonce)

@cap passes the nonce as data-cap-csp-nonce on the widget element, which Cap uses internally for its workers and inline scripts. @capScripts passes the nonce as the standard nonce attribute on the <script> tag.

CSP headers

Cap's widget relies on Web Workers and WebAssembly for the Proof-of-Work computation. A strict CSP must account for this beyond the script nonce:

Content-Security-Policy:
  script-src 'nonce-{nonce}' 'strict-dynamic';
  worker-src blob:;
  wasm-unsafe-eval;

worker-src blob: is required because the widget spawns workers via Blob URLs. wasm-unsafe-eval is required for the WebAssembly hash computation.

Middleware

Protect any route by applying the cap.verify middleware:

Route::post('/contact', [ContactController::class, 'store'])
    ->middleware('cap.verify');

Returns HTTP 422 with the message Cap verification failed. if the token is missing or invalid.

Validation rule

Use CapRule inside a Form Request or an inline validator:

use LaravelCap\Rules\CapRule;

public function rules(): array
{
    return [
        'cap-token' => ['required', new CapRule],
        // other fields...
    ];
}

Facade

use LaravelCap\Facades\Cap;

if (Cap::verify($request->input('cap-token'))) {
    // token is valid
}

Service (dependency injection)

use LaravelCap\Cap;

class ContactController extends Controller
{
    public function __construct(private readonly Cap $cap) {}

    public function store(Request $request): RedirectResponse
    {
        $this->cap->verifyOrFail($request->input('cap-token'));
        // ...
    }
}

verifyOrFail() throws a CapVerificationException if the token is invalid.

Testing

composer install
./vendor/bin/phpunit

License

MIT