Legal Consent For Laravel Laravel Package

Getting Started

The package gives you documents (terms, policies, DPAs), their versions, and an append-only ledger of who consented to what, with a hash chain you can verify later.

1. composer require pushery/legal-consent
2. Publish and run the migrations, then run the doctor:

   php artisan vendor:publish --tag=legal-consent-migrations
   php artisan migrate
   php artisan legal-consent:doctor
   

   doctor is the first place to look when something is off: it names the WireKit floor, checks your config, and tells you what is missing.
3. Publish the config if you need to change tenancy, notice routing, or retention.
4. Your first use case is almost always the same: create a document, publish a version of its text, and record a consent against it. Do that end-to-end in a test before wiring it into a controller — the hash chain means a mistake in the record shape is annoying to unwind later.

If you want the shipped UI rather than your own Blade, install pushery/wirekit at 2.67.0 or above — that is the oldest release the package's views are tested against, and below it auto silently falls back to plain views.

Implementation Patterns

Sources drive versions. A source is the thing that knows what your legal text currently says. For each document it returns a RawDocument carrying the text and, optionally, sourceVersion — whatever revision number the upstream system (a CMS, a translation tool, a contract store) assigns. As of v0.47.0 this is first-class:

• sourceVersion is recorded, never interpreted. It lands on the published version as source_version and on every consent as document_source_version, and is exposed through history(). It does not influence ordering or comparison.
• A source returning both a SemVer version and a source version keeps SemVer in charge; the source version rides along for traceability back to the upstream system.
• A source returning only a source version publishes each new one as the next minor of the active version, with the first as 1.0.0. That makes sourceVersion the natural choice for content teams who think in "revision 14 of the handbook", and SemVer the choice for anything you plan to reference contractually.

Idempotent publishing. With source-version-only sources, the package refuses to publish changed text under a source version it has already published. This is the behaviour you want: a scheduled publish command can run every five minutes and only real upstream changes move the version. Treat the refusal as an assertion, not an error — it means your source and the package agree the text is unchanged.

Record consents through the package, never by hand. The record hash chains each row to its predecessor. v0.47.0 folds document_source_version into that hash only when present, so pre-0.47 rows keep their existing hashes and no re-chaining is needed. Any bulk import you write must go through the same code path or you will break verify-ledger.

Put verification in CI and in your scheduler. legal-consent:verify-ledger is cheap and is the one thing you actually want alerting on. Pair it with a nightly run and a real alert, not a log line.

Deploy hooks. Three commands map cleanly onto deploy steps: legal-consent:cache-flush after config changes, legal-consent:rerender after you change a Blade view or a document template, and legal-consent:changes when you want a readable digest of what moved since a release (good for support and for your own changelog).

Notices and heartbeats. Failed notice dispatches emit their own heartbeats. There are now seven names that are sent only when a run failed — including legal-consent:dispatch-notices.canceled, added in 0.45.0. Alert on all seven; the documentation previously said six.

WireKit views. Publish with --tag=legal-consent-wirekit and customise freely, but keep the upstream auto mode in mind: if WireKit is absent or too old you get the plain views, so a local override plus a downgraded WireKit can look different from what you tested.

Multi-tenancy. The four commands missing from the Boost skill until this release (rerender, changes, cache-flush, verify-ledger) all take tenancy into account. If you run per-tenant, pass the tenant explicitly in scheduled jobs rather than relying on ambient resolution.

Gotchas and Tips

• Run the new migration. 0001_01_01_000041_record_the_version_its_source_counts adds source_version and document_source_version. If you publish migrations rather than loading them from the package, publish this one and run it before deploying code that writes source versions.
• Do not backfill source_version or document_source_version. Old consents hashed without them and must stay that way; writing a value in changes the hash the consent was recorded under and verify-ledger will fail.
• A typo fix upstream still needs a new source version. The package treats "same source version, different text" as a contradiction and refuses. Bump the revision in the upstream system, even for a comma. If that is impractical for your workflow, don't opt into sourceVersion — use SemVer only.
• sourceVersion will not sort. It is opaque and stored verbatim; "9" vs "10" and "v2" vs "2" are not normalised. Never build ordering or "latest" logic on it.
• WireKit version pinning. Below 2.67.0, auto quietly serves plain views. legal-consent:doctor names the floor — check it after any composer update that touches WireKit.
• vendor:publish --force clobbers your view edits. The dialog fixes in 0.47.0 ("Open as a page" is now a button, text fills the dialog) only reach you via php artisan vendor:publish --tag=legal-consent-wirekit --force. Diff your customisations first; if you never customised, just force it.
• PHPStan on published migrations. Pushery\LegalConsent\Support\TableLookup is public API as of 0.47.0, but migrations you published before this release still call it under the old assumption. Republish them, or add an ignore — the package can't fix files in your namespace.
• sqlens attributes are inert without sqlens. Seven migrations carry #[NoSqlOnDriver]. They do nothing unless pushery/sqlens-for-laravel is installed; it's only a suggest, so there's no cost either way.
• history() is your debugging surface. When a consent looks wrong, history() shows the source version recorded on it alongside the SemVer version — usually enough to tell "the source published the wrong thing" from "we recorded the wrong thing".
• Extension points worth knowing: a custom source returning RawDocument with sourceVersion is the intended integration seam for third-party content systems; published migrations and WireKit views are the intended override seams. Everything else (hash computation, version resolution) is deliberately not yours to replace.