Managing legal texts
Two Livewire screens ship as publishable stubs — a manager (releases a document as one version in every language that is ready) and a per-locale editor.
They are opt-in and fail-closed
Name a Gate ability in admin.ability and define it. With the ability unset, or the Gate
denied, both screens return 404 and never reveal they exist — there is no ungated publish
path.
The ability is checked when the component boots, which happens on every request it serves. That includes the Livewire update requests a click sends, and those go to Livewire's own endpoint rather than through the middleware of the route you mounted the screen on. So you need no middleware of your own for this, and revoking the ability takes effect on the next click rather than on the next page load.
// config/legal-consent.php
'admin' => ['ability' => 'manage-legal-texts'],
// a service provider
Gate::define('manage-legal-texts', fn ($user) => $user->isLegalAdmin());
Mounting them
Mount them as Livewire components inside your own admin routing:
<livewire:legal-consent.legal-text-manager />
<livewire:legal-consent.legal-text-editor :document-key="'terms'" :locale="'de'" />
The editor mounts with a document key and a locale (it edits one draft at a time); the
manager takes no parameters.
The WireKit variants are served automatically when WireKit ≥ 2.70.0 is installed. Publish the
plain stubs with --tag=legal-consent-views to customize them, or the WireKit ones with
--tag=legal-consent-wirekit (see
the WireKit-native variant). The editor sanitizes on
store, so its preview is the exact bytes a publish freezes.
The WireKit editor's toolbar is deliberately narrow: bold, italic, strikethrough, link, and the two list types. It offers only formatting the sanitizer keeps, so nothing an admin applies can vanish between typing it and storing it. The plain stub is a textarea — you write the markup yourself, and the same sanitizer decides what survives.
That guarantee runs one way. The sanitizer keeps more than the toolbar can create — tables
(table, thead, tbody, tr, th, td), headings, blockquote, pre/code, sub, sup,
abbr, mark, and the number an ordered list starts at (<ol start="3">, which CommonMark
writes for a list that goes on after a table) — because a legal text does not only come from that
toolbar. It also comes from a seeder, an import, or legal-consent:publish, and it renders exactly
as written.
The rich editor's engine is your application's dependency, not this package's (WireKit reads
window.wirekitEditor, and this package ships no editor configuration at all). A Tiptap factory
built on StarterKit alone does not know a table node — so it drops it while parsing, before you
have touched anything. The document looks emptied the moment the screen opens, and the next save
stores that loss. Nothing errors, because nothing went wrong from the editor's point of view.
So: if your texts use a tag beyond the toolbar's own, register the matching extension in your
editor factory (@tiptap/extension-table and its row/cell/header parts, for the table case), or
keep those documents out of the rich editor and edit them through the plain stub, which passes your
markup to the sanitizer untouched.
To prove your editor keeps them, test it against the sanitizer's own list rather than a copy of it.
LegalHtmlSanitizer::allowedElements() returns every element a sanitized text keeps, and
LegalHtmlSanitizer::allowedAttributes() the attributes each of them may carry, so the test follows
the package when the list grows.
Binding Pushery\LegalConsent\Contracts\LegalTextTranslator enables the editor's
"Translate" action; a machine translation is always produced unreviewed and must be reviewed by a
human before it can be released.
A translator whose answer leaves nothing to store throws Pushery\LegalConsent\Exceptions\TranslationRefused rather than returning: TranslationRefused::truncated() for an answer cut off at one of its limits, of its length or of its time, and TranslationRefused::declined() for a text it declined. The editor says why and what to do next, and a queued translation records the refusal for the editor rather than failing its job, so none of them lands in failed_jobs. Never return a translation that stops in the middle of a clause. Any other exception is a defect and fails as one.
Take the translation off the request
'translation' => [
'queue' => true, // default: false
'connection' => 'redis-legal', // default: null — your default connection
'queue_name' => 'legal-translations', // default: null — that connection's default queue
],
The editor calls your translator inline by default, which is right when it answers quickly and wrong when it does not: a privacy notice is around 15 kB of text — an ordinary length for one and a long time for a language model — and a consumer measured that inline call ending in a 500 twice in one day.
With translation.queue on, the action returns immediately, a queued job does the work, and the
editor polls until the draft appears. It needs a queue worker, which is why it is off by default:
off is the behavior that needs no infrastructure.
The duration is not this package's to guess. LegalTextTranslator is your binding and might answer
in microseconds or in minutes, so the answer is not a longer timeout — any limit chosen here would be
wrong in both directions — but a request that does not wait.
The queued translation runs as the admin who asked for it. A worker has nobody signed in, so a translator that bills or limits per user would read nobody: the job carries the identifier of the admin who pressed the button and the guard it read them from, signs that user in for your translator's call alone, and puts the worker back the way it found it afterwards. Your translator therefore reads the acting user the same way it does on a request, with no extra parameter. An admin who is gone by the time the worker runs translates unattributed rather than failing.
Give it a lane of its own. With both keys unset the job goes where your default jobs go, and
that is the wrong place for a call measured in minutes: a worker configured for short jobs is killed
at its timeout long before a language model answers, and raising that timeout would apply to every
job your application runs. Point these two keys at a connection whose retry_after and worker
timeout suit the call, and the rest of your queue is unaffected. An empty string counts as unset, so
an env-backed key that exists and is blank still means the default.
Nothing else changes: the job produces the same unreviewed machine draft the inline path produces, and the human review gate is untouched.
Every finished run ends in a sentence on the editor. A translation that arrives is announced and replaces the text on screen. One that does not — a translator that could not answer, a document the parser refused, a worker killed at its timeout or replaced mid-job — says that it ended, and carries the reason wherever there is one a person can act on, worded in the language of the editor that reads it. It never claims a translation that did not happen: a run that left the draft exactly as it was announces nothing of the sort. The draft is untouched in every one of those cases, so pressing Translate again is safe and answers the same way.
Every editor open on the draft takes the result, not only the one that pressed Translate. A second admin's editor, or the same one after a reload, waits on the running translation as well and takes its text when it lands. While it runs, the Translate button is disabled and says so, and a press that reaches the server anyway is answered with a sentence rather than a second job: a translator that bills per call is not paid twice for the same text.
What the manager's release publishes
The manager releases a document in the mode a material change of its type takes: an active re-consent for a contract or a real consent, info-only for a privacy notice, which is acknowledged and never gated, and a silent activation for an informational page. Until 0.32.0 it used an active re-consent for every document, which the publisher refuses for a privacy notice, so no privacy notice could be released from the manager.
An active re-consent has to raise the major version, because the gate compares major versions. A contract or a consent released from the manager as a minor or a patch comes back as a status message naming the version to publish instead, and nothing is written. See The four notice modes.
A release covers every language whose draft is reviewed and still matches its source, and always the source language. A language left out, because its translation is not written, not reviewed or was discarded, keeps the version it has live, and its readers stay bound to the text they accepted in their language until its own translation is released. The manager names those languages beside the release button, so leaving one out is a decision you see before you make it. The WireKit manager names them again in the dialog that confirms the release; the plain one has no such dialog and releases on the click. This holds for a contract and a consent as well: nobody is bound in a language they did not read, the gate reads the version of the reader's language, and a change notice reaches the people who agreed in a language that changed. Two versions of one document can therefore be in force at once, one per language, and every ledger row names the version and the language it was given in. When the source itself is not ready, nothing is released, and the overview names the source and why. While every language of the release is live as it is drafted, there is nothing to release: the manager turns the button off and names the reason below it, and a release asked for from a page loaded before the last one is refused with the same reason.
Neither screen asks for a version number. A release derives it with
LegalDocumentReleaser::nextVersionFor(): the next major for a mode that gates, the next minor for
one that does not, and 1.0.0 for a text published for the first time. A version you set yourself
with LegalDraftWriter::setVersion() is used as long as no release has used it yet. One that a
release already used for another text is replaced, so a changed text can be released again, and
releasing an unchanged text again publishes the version it already has.
The count under a release
Once a release is written, both screens say how many people it reaches: everybody who agreed to an earlier major version in one of the released languages, or, for a mode that does not gate, everybody who agreed at all. Each person counts once, whichever of those languages they agreed in.
The count reads every consent of the document in those languages, so it grows with the ledger, and
it runs inside the request that made the release. admin.release_count_seconds is the time the
database gets for it, 5 seconds unless you set it. On PostgreSQL and MySQL a count that takes longer
is stopped: the release stands, and the status line names it without the number. 0 skips the
count, and null waits for it however long it takes. SQLite has no statement timeout and counts to
the end under any value above 0.
A release screen of your own gets the same answer from
LegalDocumentReleaser::affectsReleaseWithin($released, $seconds), which returns null when the
count did not finish in time. affectsRelease($released) counts without a limit.
Moving a document from Markdown to the drafts store
The acceptance sentence travels with a version: it is frozen into the published row and copied
into every consent given under it. A Markdown source carries its sentence in the front matter
(ui_wording:), and the drafts store does not read that file. It takes the sentence from the
translation files, legal-consent::wording.{key}, so a document you move keeps its text and changes
its sentence to the package's own unless you set yours there:
// lang/vendor/legal-consent/en/wording.php
return [
'terms' => 'I accept the Terms of Service.',
];
Do it for every language before the first release from the drafts store. legal-consent:publish
and its --dry-run name the old and the new sentence whenever a version changes it, so a sentence
that moved by accident shows up before or after the publish rather than in the next dispute.
Then hand the store the texts themselves. The editor opens empty for a text that has no draft, so
once a document's source is the drafts store, run:
php artisan legal-consent:draft-from-source # every document on the drafts store
php artisan legal-consent:draft-from-source terms --reviewed # one document, reviewed in the repository
It reads each text from the markdown source, or the one --from= names, in every configured
language with the default language first, through the pipeline the editor saves with, and puts the
version the source text declares onto the document. A text that has a draft already is kept, so a
second run changes nothing somebody edited, and a text on version 0.0.0, the version of a text
nobody has written yet, is skipped. Nothing is published, and nothing is marked reviewed unless
--reviewed says the texts were reviewed where they were written. Even then a translation is marked
only when its source text was written in the same run, because reviewing it against a source
somebody has edited since would claim a match nobody checked. With tenancy on, --tenant= names the
tenant to write into.
If you go on writing the texts in the repository and review, translate and release them in the admin
area, --refresh carries a change in the files over to the drafts:
php artisan legal-consent:draft-from-source --refresh --dry-run # name what would be replaced
php artisan legal-consent:draft-from-source --refresh
It replaces a draft with the text of the source when the draft still says what its published
version says, and puts the version the source declares onto the document. A difference in rendering
alone, as after a renderer update, is no edit. A draft whose text differs from its published version
was edited in the admin area: it is kept, and the run names it. A draft of a text nothing is
published of is kept as without --refresh. A replaced text waits for a review again, whatever
--reviewed says, a translation of a replaced source text counts as stale, and nothing is
published. --dry-run names what a run would draft and replace, and writes nothing.
A text still waiting for its first release has no published version to tell an edit from the
import, so --refresh keeps its draft. When you know nobody edited those drafts in the admin area,
say so with --replace-unchecked:
php artisan legal-consent:draft-from-source --replace-unchecked --dry-run # name what would be replaced
php artisan legal-consent:draft-from-source --replace-unchecked
It does what --refresh does, and also replaces a draft of a text nothing is published of with the
text of the source. Each draft replaced that way is named at the end of the run. A draft that differs
from its published version is kept all the same, so the option never overwrites an edit the run
could see.
A document of your own needs a heading and a sentence
A document the package does not ship, such as a data processing agreement under dpa, has no line
in the translations until you write one. Without a title it would be published with its key as its
heading, frozen into the version in every language, so the publisher refuses it, in a --dry-run
as well, and the overview and the editor word the refusal. Without a sentence of its own it asks for
the generic one, "I have read and accept the terms.", which names no document. Give it both, in every
language you publish:
// lang/vendor/legal-consent/en/titles.php
return [
'dpa' => 'Data Processing Agreement',
];
// lang/vendor/legal-consent/en/wording.php
return [
'dpa' => 'I conclude the Data Processing Agreement.',
];
legal-consent:doctor names every registered document whose heading would be its key or comes from
another language, and every one that would ask for the generic sentence or has none at all.
legal-consent:publish --dry-run, the editor's Save and publish and the overview's release name
the heading a version would freeze, and the dry run and the editor the sentence as well. When the
texts come from Markdown files whose front matter carries title: and ui_wording:,
legal-consent:draft-from-source prints the lines for these two files, because the drafts store
does not read the front matter. A Markdown source takes both from its front matter, and the
publisher refuses a file without title: the same way.
From the shell
Everything the admin area does for a release has a command, for a server that runs without it.
php artisan legal-consent:status lists every document by language, with how far its text is and
the command that publishes it, php artisan legal-consent:review <key> --by=<name> signs drafts off,
and php artisan legal-consent:publish releases them. See the
command reference.
Publishing a text for the first time
A text that has never been published has nothing anybody could object to, so the editor offers no objection window for it. It offers Publish now instead, which publishes every language that is ready at once, in the mode of the document's type: a contract asks for its first acceptance, a privacy notice is announced, and an informational page goes out silently. No period applies. Once a version is out, the editor offers the objection window for the next change, as described below.
A language that was never published while another one holds a version in force can be added on its own. The editor of that language offers Publish the language, which publishes it under the version the other languages hold, in the mode that version went out in. It changes nothing about the contract: a consent counts across languages, so whoever accepted the version in another language holds it here as well. The button is offered for a version that asks for acceptance or went out silently, once it is in force, and while the source still carries that version. A version released with an objection window, or announced to every party, adds its languages with the next change.
Saving and publishing in one go
For the change you make again and again, Save and publish saves the draft and opens a short dialog of everything the release takes: the languages it releases and those it leaves out with their reason, the version it becomes, the way it is released with what that means for the people it concerns, the dates and the regime. The dialog offers only the ways the document's type can be released in, its type's own first: a contract can ask everyone to accept it again, go out with an objection window, be announced or change silently; a privacy notice is announced or changed silently; an informational page changes silently. Confirming signs off the language you are editing as reviewed by you and releases. A change with an objection window takes the dates of its form.
Leaving with unsaved changes. In the WireKit views the editor says beside Save that the text holds what the draft does not have yet, and asks before the page is left: a link inside the application in WireKit's dialog, a reload or a closed tab in the browser's own question. Only a save or a discard counts the text as saved; a request of another button sends the text along without storing it, so it stays unsaved. The release form with an objection window counts its class and its two switches the same way, until the release went through. The plain views do not ask.
Releasing a change that binds by silence
The editor can release a change as deemed consent — the mode where silence binds if the objection window closes without an objection (§ 308 Nr. 5 lit. b BGB). Until 0.23.0 only the CLI could drive it, so an application with an admin UI had no in-app path to a capability the package implements end to end.
It sits in the editor rather than on the manager's overview grid, and that is deliberate: a release that binds people by their silence is a legal call about one specific change, and the editor is the screen where somebody has actually read the text. The editor offers it only for a contract's terms: a privacy notice is acknowledged, a consent is never deemed, and the publisher refuses the mode for both.
Seven fields drive it: three dates, the regime, the change class and two flags.
| Field | What it sets |
|---|---|
| announce date | when the notice goes out |
| objection deadline | the date an objection has to arrive by |
| effective date | when the change takes effect |
| regime | the legal regime the change is made under, which decides the statutory minimum of the window |
| change class | your own classification tag, the same one the command line takes |
| offers termination | the change grants a free right to terminate (§ 675g Abs. 2 BGB, P2B Art. 3) |
| keeps unmodified on offer | whoever objects stays on the version they already hold |
The form opens on a window that already holds: announced today, the objection deadline on the first day the publisher accepts for the document and its regime, and effective the day after. Moving the announcement or the regime moves the two later dates along until you set them by hand, and no date field offers a day before its first possible one. Under the dates the form names the minimum in days with the rule behind it, such as § 308 Nr. 5 BGB for a deemed consent or § 675g Abs. 1 BGB with its two calendar months for a payment contract. The regime starts on German standard terms for a contract, and every regime is named and explained in the list. The change class is optional, the two switches say when they are needed, and the preview of the text opens folded.
The three dates and the regime are required. A change that binds by silence rests on its window, and without a regime no statutory floor applies to it, such as the two months § 675g BGB demands for a payment contract. Those months count backward from the day the change takes effect, and that day is not counted: for a change in force on 1 September, the notice has to reach the reader by 30 June. The screen names every empty field before anything is released.
A window that runs backwards, falls short of the statutory lead time, or carries a date the screen
cannot read comes back as a status message, not an exception — and the message carries the
package's own numbers: which minimum applied, and which dates it read. A date is read strictly:
2026-02-31 is refused by name rather than rolled forward to March 3rd, because the value ends up
in an append-only proof row that a later correction cannot reach. That is the point of driving this from the editor rather than only
from the CLI. A release the package refuses is a release you can correct on the spot.
The same screen refuses to release while the source language is not ready — an unreviewed draft, a missing text — and names it with its reason. A translation that is not ready stays out of the release and keeps the version it has live. A refusal of the version itself, such as a version below the active one or a major that has to gate, is worded in the screen's language too, on this screen and on the overview.
After the release, legal-consent:close-objection-windows is what actually closes each window and
turns silence into an acceptance. It is scheduled by the package; you do not add it yourself.
Four heartbeats decide whether that silence binds, and they only fire when it does not.
legal-consent:close-objection-windows.unproved reports subjects that could not be deemed because
no § 308 Nr. 5 lit. b warning is on record as delivered to them by the objection deadline, and
legal-consent:close-objection-windows.late those it reached too late to leave them the objection
period, after the deadline or too close to it. legal-consent:dispatch-notices.expired reports versions whose deadline
passed before their notice went out, so nothing was sent, and legal-consent:dispatch-notices.deficient
versions whose notice went out without its mandatory content — silence cannot bind against those
at all. Each of these is repaired by a new version with a new objection deadline, not by sending the
notice again. Alert on all four by name; see
Retention and sweeps.
Published versions are frozen
A published legal_documents row is immutable proof — the exact sanitized text a subject was shown
and the hash the ledger snapshots, one text because they are one row.
A database trigger (PostgreSQL, MySQL, SQLite) and a model hook reject any edit to a proof column
after publish; a direct write raises LegalDocumentFrozenException (through the model) or a
database error (raw SQL).
Correcting a text is a new version, never an in-place edit.
A version a consent points at cannot be deleted either: its row holds the text that consent was
given to, and the ledger keeps only its hash. A trigger refuses the DELETE on all three engines,
and on PostgreSQL a TRUNCATE of legal_documents as well while any consent points at a version
in it. MySQL runs no trigger on TRUNCATE TABLE, so there the statement is held back only by the
privileges of your database user: it needs DROP. A version nobody consented to stays deletable.
Retire a version with is_active = false instead.
Pages nobody agrees to
An Impressum, a cookie policy or an accessibility statement is a page you must publish and
keep current — and it asks the reader for nothing. Such a page is registered with the
informational basis, and the shipped registry already carries imprint as the worked example:
'imprint' => [
'source' => 'markdown',
'legal_basis' => 'informational',
],
Add a cookies or accessibility entry the same way; all imprint needs is its Markdown file.
It uses everything on this page — the editor, the review gate, the translation seam, the sanitizing pipeline, the frozen published row — and none of the consent machinery. It never appears in the registration checklist, never writes a ledger row, never gates access, and never sends a notice.
Publish it silently:
php artisan legal-consent:publish imprint de --editorial
The other modes are refused for this class. Each of them describes an audience that does not exist here: there is no acceptance to deem or to re-request, and the notice sweeps resolve their recipients from ledger rows — which this class never writes.
This is the one class that falls back. If en is not published, an informational page serves
your default_locale instead of nothing. Every other class keeps the strict behavior on
purpose — see below.
A release of such a page covers every language whose draft is reviewed and still matches its
source, and always the source language. A translation that is written but not reviewed yet does
not hold the page back: that language keeps the version it has live, or serves your
default_locale where it has none. When the source itself is not ready, nothing is released, and
the overview names the source and why. An acknowledgment with locale_fallback is released the
same way.
Its ui_wording is null, and that is the point rather than an omission. Every other class
freezes the exact acceptance sentence a subject clicked into that column, copies it verbatim into
each ledger row, and folds it into the hash chain — so whatever lands there is permanent. A page
that binds nobody has no such sentence, and there is no honest value to invent for one. If your
own view renders the wording, guard it:
@if ($document->uiWording !== null)
<p>{{ $document->uiWording }}</p>
@endif
A wording supplied by the source for an informational page is dropped rather than stored, for
the same reason: honoring it would freeze a misunderstanding into a column nothing can correct.
Where the heading comes from depends on the source, and the two are not interchangeable. A
markdown page — the example above — takes it from the file's frontmatter title:. A drafts
page takes it from lang/*/titles.php, looked up by the document key: imprint, cookies and
accessibility ship translated in all seven locales, and a key with no line there is refused at
publish rather than published under its raw key. Editing titles.php has no effect on a
markdown-sourced page.
Rendering the public legal page
Render a public page from the frozen row — never the source, which can drift between an author's edit and the next publish:
use Pushery\LegalConsent\Facades\Consent;
$document = Consent::published('terms', app()->getLocale());
// $document?->html is the exact stored bytes and $document?->contentHash the exact stored hash —
// the same text the ledger proves. Returns null before that locale is published (render an "in
// preparation" shell), and never falls back to another locale.
Render those bytes unescaped:
@if ($document !== null)
<h1>{{ $document->title }}</h1>
{!! $document->html !!}
@endif
{!! !!} is correct here and {{ }} is not, which is worth stating because the habit runs the
other way. The value is HTML the package produced itself: the Markdown source went through the
render pipeline and the package's one sanitizer before the row was frozen, and content_hash is
the hash of exactly these bytes. Escaping them shows the reader visible tags; putting them through
a second sanitizer changes them, and the page then no longer matches the hash the ledger carries.
Everything else about the document — its title, its acceptance wording — is escaped as usual.
legal-consent:verify-documents re-checks every published row against its stored hash and
flags notice-mode divergence across a version's locales — see the
command reference. It also reports a version that was released while it
was still a placeholder: one on 0.0.0, or one whose text carries LEGAL-PLACEHOLDER or another
marker you list in placeholder_markers. A document on the draft store that has never been
released is reported too, with its key and locale, because its page shows the file it ships with
until the first release. Run it with --placeholders-fail before a launch, and a placeholder or
such a draft fails the run instead of warning.