User Consent Laravel Package

Getting Started

Check the two hard constraints before writing any code. This is a Filament plugin, not a framework-agnostic consent library. Everything useful — the consent option CRUD, the registration-time form, "My Consents", the admin list — lives in Filament resources and panel pages. Your end users therefore have to be served through an authenticated Filament panel with registration enabled. If your Filament install is a staff-only back office, you will be reimplementing the user-facing half yourself. Second, the version line is locked to the Filament major: package ^5.0 ↔ Filament 5.x, package ^4.0 ↔ Filament 4.x. Filament 5.x also pulls in Livewire 4, so audit your other Livewire-heavy packages first.

Install and publish.

composer require visualbuilder/user-consent:^5.0
php artisan vendor:publish --tag="user-consent-migrations"
php artisan vendor:publish --tag="user-consent-config"
php artisan vendor:publish --tag="user-consent-views"
php artisan migrate

The publish tags are inconsistent across asset types (user-consent-migrations, user-consent-config, user-consent-views), while the config file is filament-user-consent.php and the namespace is Visualbuilder\FilamentUserConsent. Expect to grep for the tag you need rather than guessing.

Where to look first. The README stops at setup, so plan on half a day in vendor/visualbuilder/user-consent/src:

1. src/ — find the service provider and any Plugin class. You will need to register the plugin on your panel in the PanelProvider; the README documents the install but not this step.
2. The migrations — confirm the table shape for consents and consent options, and whether re-consent inserts or updates.
3. Livewire/ConsentOptionFormBuilder — this is the page users land on, and the documented extension seam.
4. The User-model wiring — the README says "apply them to user models," so look for a trait or contract you add to App\Models\User.

First use case. Consent at registration. Spike it end-to-end: create two or three real consent options, enable registration on a panel, register a test user, and confirm (a) the form blocks registration until consents are given, (b) the emailed receipt arrives, and (c) "My Consents" lists them. That single path exercises the plugin's whole value proposition, and it will tell you within a day whether the panel-topology constraint is a dealbreaker for your app.

Implementation Patterns

Treat consent wording as seed data, not admin data. The shipped config is an empty array, which means consent option text is authored in the admin UI and written to the database — not diffable, not code-reviewable. For anything with regulatory weight, create consent options in a seeder or a data migration so the wording lands in a pull request:

// database/seeders/ConsentOptionSeeder.php
ConsentOption::updateOrCreate(
    ['key' => 'terms_of_service'],
    ['title' => 'Terms of Service', 'body' => '...', 'version' => 1, 'required' => true],
);

Confirm the actual column names from the published migration before writing this — the README doesn't enumerate them.

Model versioning explicitly. The feature "users already accepted can be asked to accept the updated consent" is the one that most needs a deliberate pattern. Two approaches exist and the docs don't pick one for you: edit the existing option's body (and rely on the package to detect the change), or create a new option row and retire the old one. Verify in source whether the package compares updated_at, a version column, or nothing at all — the answer determines your whole workflow, and it also determines whether history is append-only or overwritten. If it overwrites, either add your own audit table or accept the reduced evidentiary value knowingly.

Wire the consent gate at the right layer. The plugin handles the registration form and the redirect to consent-option-request. For users who pre-date the install, or whose terms changed, you need your own middleware or panel-level check that sends them to the consent page on login. Test the "nothing left to consent to" case explicitly — 5.0.6 fixed a 403 No required consent on exactly that path (pressing back after submitting), which tells you this class of redirect bug recurs.

Queue the receipt email. Sending a consent receipt inline on the registration request adds SMTP latency and timeout risk to your highest-traffic POST. Whether the package uses Mail::send or Mail::queue is not documented; assume inline until proven otherwise, and override or wrap it so delivery failures are retried and visible. If the emailed copy is part of your evidence trail, an undelivered email is a compliance gap, not just a UX annoyance.

Customise via the page class, not the route. 5.0.4 added pages.consent_option_form_builder to config. Subclass ConsentOptionFormBuilder and register it:

// config/filament-user-consent.php
'pages' => [
    'consent_option_form_builder' => \App\Livewire\ConsentOptionFormBuilder::class,
],

Do this on day one even if the subclass is empty. It's your supported seam for layout, branding and behaviour changes without redefining routes — and it means your first real customisation doesn't require a route refactor.

Admin visibility. The package ships a list of consents across all users. Check pagination and indexes early: consent rows grow at users × options × re-consents, and an unpaginated all-users view is a predictable performance cliff. Add indexes on user_id and the option identifier in your published migration before migrating — retrofitting them on an audit table under load is avoidable pain.

Gotchas and Tips

The README's config snippet is wrong. It shows return []; while the same document describes a pages.consent_option_form_builder key. Read the published config file (and the source that consumes it) rather than trusting the snippet — there may be other undocumented keys.

Pin the version and treat Filament majors as paired tickets. The package majors with Filament. When Filament 6 ships, you freeze until a matching release lands. Add a Renovate/Dependabot rule that surfaces a Filament major bump as a ticket requiring a matching visualbuilder/user-consent bump, so the stranding is scheduled rather than discovered.

Test the redirect flows, not just the happy path. The 5.0.5 and 5.0.6 changelog entries are both redirect/UX bugs — a jumping submit button, then a 403 on revisit. Write feature tests for: user with outstanding consents hits the page, user with none hits the page (expect redirect, not 403), user submits then presses back, user submits a partially-complete form.

Use RefreshDatabase and assert on the consent table directly. Don't rely on UI assertions alone for consent capture; query the consents table in the test so you catch a regression where the form renders but nothing persists.

Withdrawal is not evidenced. Grant, re-grant and receipt are covered. Revocation, data-subject export, per-purpose granularity and retention policy are not. If your product needs "withdraw consent," budget for building it on top of the package's models rather than expecting it — and check whether a withdrawal would even be representable in the schema before you commit to the package.

Localisation and multi-tenancy are unknown quantities. Four stars, zero dependents, one maintainer. There is no community experience to draw on for "how do I run this per-tenant" or "how do I translate the consent page." Read the source; don't assume.

Fork at adoption, not after six months of local patches. Once you're subclassing the Livewire page, overriding the mail send, and seeding options via migration, your fork cost only goes up. If the spike passes and you need anything beyond configuration, vendor the package and own it explicitly, with a named owner for Filament major upgrades.