Getting Started

Minimal Steps

Installation:

composer require spatie/laravel-honeypot

Publish the config (optional):

php artisan vendor:publish --provider="Spatie\Honeypot\HoneypotServiceProvider" --tag="honeypot-config"

Add Honeypot to a Form: In your Blade template, include the honeypot component:

<form method="POST" action="{{ route('contact.submit') }}">
    <x-honeypot />
    <!-- Your form fields -->
    <input name="email" type="text">
    <button type="submit">Submit</button>
</form>

Protect the Route: Apply the middleware to your form submission route:

Route::post('/contact', [ContactController::class, 'store'])
    ->middleware(\Spatie\Honeypot\ProtectAgainstSpam::class);

First Use Case

Scenario: Protect a contact form from spam submissions.

Add <x-honeypot /> to your form.
Apply the middleware to the route handling submissions.
Test with a bot (e.g., this tool) to verify it blocks submissions with filled honeypot fields.

Implementation Patterns

Blade Integration

Component/Directive: Use <x-honeypot /> or @honeypot in Blade templates. Both inject two hidden fields:
- my_name (configurable): Should always be empty for valid submissions.
- valid_from: Encrypted timestamp to detect rapid submissions (default: 1 second threshold).

Dynamic Forms: For dynamic forms (e.g., AJAX), manually include the fields:

form.append('my_name', '');
form.append('valid_from', '{{ $honeypot->encryptedValidFrom }}');

Middleware Strategies

Route-Level Protection:
```
Route::post('/contact', [ContactController::class, 'store'])
    ->middleware(\Spatie\Honeypot\ProtectAgainstSpam::class);
```
- Pros: Granular control over which forms are protected.
- Cons: Requires manual application to each route.
Global Middleware: Add to app/Http/Kernel.php:
```
protected $middleware = [
    // ...
    \Spatie\Honeypot\ProtectAgainstSpam::class,
];
```
- Pros: Automatic protection for all forms.
- Cons: Risk of false positives if honeypot fields are missing in some forms. Disable with honeypot_fields_required_for_all_forms: false in config.

Middleware Groups: Protect specific groups (e.g., auth routes):

Route::middleware(['web', \Spatie\Honeypot\ProtectAgainstSpam::class])->group(function () {
    Auth::routes();
});

Inertia/Vue Integration

Share Honeypot Data: In app/Http/Middleware/HandleInertiaRequests.php:

public function share(Request $request): array {
    return array_merge(parent::share($request), [
        'honeypot' => new \Spatie\Honeypot\Honeypot(config('honeypot')),
    ]);
}

Render in Vue:

<template>
    <div v-if="honeypot.enabled" style="display: none;">
        <input type="text" v-model="form[honeypot.nameFieldName]" :name="honeypot.nameFieldName">
        <input type="text" v-model="form[honeypot.validFromFieldName]" :name="honeypot.validFromFieldName" :value="honeypot.encryptedValidFrom">
    </div>
</template>

<script setup>
const form = useForm({
    email: '',
    [defineProps(['honeypot']).honeypot.nameFieldName]: '',
    [defineProps(['honeypot']).honeypot.validFromFieldName]: defineProps(['honeypot']).honeypot.encryptedValidFrom,
});
</script>

Livewire Integration

Add Trait and Property:

use Spatie\Honeypot\Http\Livewire\Concerns\{UsesSpamProtection, HoneypotData};

class ContactForm extends Component {
    use UsesSpamProtection;

    public HoneypotData $extraFields;

    public function mount() {
        $this->extraFields = new HoneypotData();
    }

    public function submit() {
        $this->protectAgainstSpam(); // Throws exception if spam
        // Process form...
    }
}

Blade Template:

<form wire:submit="submit">
    <x-honeypot livewire-model="extraFields" />
    <!-- Form fields -->
</form>

Custom Spam Responses

Extend the default BlankPageResponder:

use Spatie\Honeypot\SpamResponder\SpamResponder;

class CustomResponder implements SpamResponder {
    public function respond(): void {
        abort(403, 'Spam detected. Please try again.');
    }
}

Update config:

'respond_to_spam_with' => \App\SpamResponders\CustomResponder::class,

Gotchas and Tips

Pitfalls

Missing Honeypot Fields:
- If using global middleware, ensure all forms include <x-honeypot /> or @honeypot. Otherwise, legitimate submissions may fail.
- Fix: Set 'honeypot_fields_required_for_all_forms': false in config or use route-level middleware.
CSRF Token Conflicts:
- The honeypot fields (my_name, valid_from) must not conflict with existing form fields (e.g., name, valid_from).
- Fix: Customize field names in config:
```
'name_field_name' => 'honeypot_name',
'valid_from_field_name' => 'honeypot_timestamp',
```
Livewire Property Binding:
- Forgetting to bind livewire-model in <x-honeypot /> will cause the honeypot data to not sync with Livewire.
- Fix: Always include livewire-model="extraFields" (or your property name).
Inertia Form Submission:
- If using Inertia, ensure the honeypot fields are included in the form data before submission. Omitting them triggers spam detection.
- Fix: Verify the form includes:
```
form[honeypot.nameFieldName]: '',
form[honeypot.validFromFieldName]: honeypot.encryptedValidFrom,
```
Time Zone Issues:
- The valid_from timestamp uses the server's time zone. If your app uses a non-default time zone, submissions from users in other time zones might be flagged.
- Fix: Ensure config('app.timezone') matches your expectations.
CSP (Content Security Policy) Conflicts:
- Hidden inline styles (used to hide honeypot fields) may violate CSP if not configured.
- Fix: Enable 'with_csp': true in config and install laravel-csp.

Debugging Tips

Log Spam Attempts: Extend the SpamProtection class to log blocked requests:

use Spatie\Honeypot\SpamProtection;
use Illuminate\Support\Facades\Log;

class CustomSpamProtection extends SpamProtection {
    protected function checkForSpam(): void {
        try {
            parent::checkForSpam();
        } catch (\Spatie\Honeypot\Exceptions\SpamException $e) {
            Log::warning('Spam attempt blocked', [
                'ip' => request()->ip(),
                'user_agent' => request()->userAgent(),
                'honeypot_field' => request()->honeypot_name,
            ]);
            throw $e;
        }
    }
}