Download the PHP package djl997/simple-laravel-form-protection without Composer

Simple Laravel Form Protection

Heuristic spam scoring and submission monitoring for public Laravel forms.

Every public form submission is stored, scored against a set of configurable heuristics, and flagged when the score reaches a threshold. The intent is monitoring: nothing is blocked or rejected: your application decides what to do with a flagged submission (typically: store it, but skip the notification mail).

This package pairs well with, but does not replace, spatie/laravel-honeypot. Honeypot fields stop naive bots outright; this package scores whatever gets past them.

Installation

While the package lives locally, add it as a path repository:

Usage

The package works with both Livewire components and plain HTML forms. Both paths score and store submissions identically; they differ only in how the form's render time reaches the scorer.

Livewire

Add the trait to a Livewire component, give it a form key, and call mountMeta() when the form is rendered:

mountMeta() records the request path and the moment the form was rendered. That render time drives the timing heuristic, so a component that never calls it simply scores nothing for timing rather than being penalised.

Plain HTML forms

A Livewire component keeps its render time in component state. A plain form has no such state — render and submit are two separate requests — so the render time travels in an encrypted hidden field. Drop the Blade component inside your <form>:

Then record the submission in the controller with the FormProtection facade:

There is no calculateContentScore() hook here, since there is no component to override it on. Call the SpamScorer helpers directly for whichever fields the form has — they are the same methods the trait's helpers delegate to, and they ignore blank values.

The hidden field is encrypted with your application key and bound to the form key, so it cannot be tampered with or reused across forms. It also expires after timing.max_token_age (12 hours by default) so a token harvested once cannot be replayed forever.

A token that is missing, forged, stale, or issued for another form is not treated as spam — it scores as if the timing were never measured. This keeps the package's promise that it only ever monitors. A form that omits the Blade component still works; it just loses the timing signal.

Scoring the content

In a Livewire component, override calculateContentScore() to score the submitted fields. Three helpers cover the common cases:

Each helper takes the value to score plus the running total, and returns the new total. They ignore blank values. For plain HTML forms, call the equivalent SpamScorer methods in the controller as shown above.

Thresholds

A submission is flagged when its score reaches the threshold. The default lives in config; a Livewire component can tighten it by overriding the method, and a plain form can pass a threshold as the fifth argument to FormProtection::record():

Keep this method public. The trait declares it public, and narrowing it to protected in a subclass is a fatal error in PHP.

Configuration

config/simple-laravel-form-protection.php holds the threshold, the model class, and every weight and magic value the heuristics use. Defaults are tuned for a Dutch/Belgian audience:

Set any weight to 0 to disable that rule. Tune the lists to your own audience — the defaults penalise perfectly ordinary submissions from outside the Benelux.

Retention

Genuine submissions you soft-delete are pruned after pruning.retention_days via Laravel's own model:prune. Spam is kept for review and then permanently deleted:

Schedule both in routes/console.php:

Extending the model

Point model in the config at your own class extending Djl997\SimpleLaravelFormProtection\Models\FormSubmission to add relations or scopes. The packaged model records user_id for authenticated submissions but deliberately declares no foreign key, since it cannot know your users table.

Testing