hettiger/spa-honeypot

Honeypot package for Single Page Applications

v0.3.0 2025-10-06 16:11 UTC

Requires

• php: ^8.2|^8.3|^8.4
• illuminate/contracts: ^10.0|^11.0|^12.0
• spatie/laravel-package-tools: ^1.13.0

Requires (Dev)

• larastan/larastan: ^2.0.1|^3.0
• laravel/pint: ^1.0
• nunomaduro/collision: ^7.0|^8.1
• nuwave/lighthouse: ^6.0
• orchestra/testbench: ^8.0|^9.0|^10.0
• pestphp/pest: ^2.0|^3.0
• pestphp/pest-plugin-laravel: ^2.0|^3.0
• phpstan/extension-installer: ^1.1
• phpstan/phpstan-deprecation-rules: ^1.0|^2.0
• phpstan/phpstan-phpunit: ^1.0|^2.0
• phpunit/phpunit: ^10.0|^11.0

Suggests

• nuwave/lighthouse: This package supports Lighthouse PHP (optional)

Conflicts

• nuwave/lighthouse: <6.0

MIT

• Martin Hettiger

• laravel
• hettiger
• spa-honeypot

README

Helps to protect SPA's (Single Page Applications) against SPAM without using cookies or user input.

Installation

composer require hettiger/spa-honeypot
php artisan spa-honeypot:install

Usage

1. Add the form.honeypot, form.token or form middleware to a forms target route

Route::post('form', fn () => 'OK')->middleware('form');

The form middleware group simply combines form.honeypot and form.token so you don't have to. Using just form.token protection without the form.honeypot middleware or vise versa is supported.

1. Use one of the corresponding frontend libraries to make form token requests

Lighthouse GraphQL API

1. Add the form.token.handle middleware to the lighthouse.route.middleware config

// config/lighthouse.php — must be published

'middleware' => [
    // …

    'form.token.handle',
],

1. Register the honeypot scalar in your graphql/schema.graphql file

scalar Honeypot @scalar(class: "Hettiger\\Honeypot\\GraphQL\\Scalars\\HoneypotScalar")

# …

1. Add a honeypot field to any input that you want to protect against SPAM

input SendContactRequestInput {
    # …
    honey: Honeypot
}

The field config is not being used in GraphQL context.

1. Add the @requireFormToken directive to any field that you want to protect against SPAM

# e.g. graphql/contact.graphql

extend type Mutation {
    sendContactRequest(input: SendContactRequestInput): SendContactRequestPayload @requireFormToken
}

1. Use one of the corresponding frontend libraries to make form token requests

Customizing Responses

You may provide custom error response factories using the config:

return [
    // …
    
    'honeypot_error_response_factory' => \Hettiger\Honeypot\ErrorResponseFactory::class,
    'form_token_error_response_factory' => \Hettiger\Honeypot\ErrorResponseFactory::class,
];

Alternatively you can provide a simple Closure anywhere in your application:

use Hettiger\Honeypot\Facades\Honeypot;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    // …

    public function boot()
    {
        $errorResponseFactory = fn (bool $isGraphQLRequest) => $isGraphQLRequest
            ? ['errors' => [['message' => 'Whoops, something went wrong …']]]
            : 'Whoops, something went wrong …';

        Honeypot::respondToHoneypotErrorsUsing($errorResponseFactory);
        Honeypot::respondToFormTokenErrorsUsing($errorResponseFactory);
    }
}

You don't have to worry about adding the form token header yourself. It'll be added for you automatically.

Testing

composer test

Frontend Libraries

• Angular

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

• Martin Hettiger

License

The MIT License (MIT). Please see License File for more information.