Laravel Legal Documents Laravel Package

Getting Started

• Install with composer require vlados/laravel-legal-documents. In v2 Spatie Laravel Translatable is no longer pulled in — add it yourself only if you need the bundled adapter (composer require spatie/laravel-translatable).
• Publish and run migrations, config, and views:
  • php artisan vendor:publish --tag="legal-documents-config" (tag names may vary — check the README)
  • php artisan vendor:publish --tag="legal-documents-migrations" then php artisan migrate
  • php artisan vendor:publish --tag="legal-documents-views" if you intend to touch markup/labels
• First use case: gate registration or checkout on a versioned terms/privacy document. Seed the document record, publish a version with the source-language body, render the acceptance form, store the acceptance, and later check “has this user accepted the current version?” rather than “has this user accepted anything?”.
• Where to look first:
  • the published config file — this is where the source language and translation driver live in v2
  • docs/upgrading-to-v2.md and docs/translations.md (linked from the release)
  • the acceptance migration: note that acceptances are keyed to a document version ID, and v2 explicitly preserves those IDs
• Decide up front whether you are single-language. If yes, skip translation migrations entirely — v2 works standalone and keeps working even if Spatie is later removed from the app.

Implementation Patterns

• Version-first content model. Treat documents as stable identities and versions as immutable content. Publish a new version for any wording change; never edit a published version in place, or acceptance records stop meaning what they claim.
• Acceptance checks against the current version. Resolve the current version, then compare it to the user's stored acceptances. This gives you a clean middleware/policy guard for routes and a cheap check in a form request.
• Localized output, unlocalized source. Your source-language scalar fields stay authoritative. Translations are additive; the package falls back to the complete source document when a translation is missing rather than rendering a half-translated page. Design UI copy around that (don’t assume partial translations exist).
• Translation driver setup (v2). Enabling more than one language is a three-part opt-in: set the driver/source language in config, register the driver (bundled Spatie adapter or your own TranslationDriver implementation), and run the adapter's migration so translation tables exist. Installing Spatie alone does nothing.
• Custom backends. If you already store translations in JSON columns, a translation service, or a CMS, implement the TranslationDriver contract rather than bending the Spatie adapter. Keep the driver thin — read/write per document version and locale — and let the package handle fallback.
• Localized recipient notifications. Notifications are localized to the recipient, so queue them with the recipient's locale set (or send through a locale-aware job) rather than the request locale. This is the difference between a correct and an embarrassing acceptance email.
• Filament 4 admin. Register the plugin and use the translation tabs (English/Bulgarian labels ship in the package). Untouched languages are preserved on save, so editors can add a Bulgarian tab without wiping English content — but verify tab-level validation rules before letting non-technical staff edit.
• Version copying is transactional and translation-aware. Copying a version duplicates every stored translation and deliberately does not copy acceptances. Use it as your “draft next version” workflow; expect new version IDs and therefore a fresh acceptance requirement for users.
• Language overrides. Publish package language files and override labels for your domain (e.g. “Terms” → “Customer Agreement”) instead of editing Blade views where possible.

Gotchas and Tips

• The upgrade is mostly dependency hygiene. Declare Spatie explicitly if you use it; otherwise v2 is a drop-in for single-language apps — routes, scalar source fields, version IDs, and acceptances are preserved.
• Fallback precedence trips people up. Spatie's explicit global fallback wins; the package config supplies the fallback only when Spatie's is unset or null. If a page renders in the wrong language, check the Spatie config first, then the package config.
• Filament 4 is required for the admin integration, and the Lara Zeus translation plugin is no longer needed. Remove it during the upgrade or you will end up with duplicate/conflicting translation UI.
• Review published Blade views and language overrides after upgrading. v2 changed translation APIs and labels; stale published views are the most likely source of blank or untranslated output, and they fail quietly rather than throwing.
• Missing adapter migrations look like “translations don’t save.” If saves appear to succeed but the localized page still shows source content, confirm the translation tables exist and the driver is actually configured — silent fallback masks misconfiguration.
• PostgreSQL concurrency. v2 hardens locale writes and version copying (serialization rollback/retry is covered in CI). Keep your own writes inside the package’s transaction boundaries; don’t wrap version creation in an outer transaction that swallows retries.
• Don’t copy acceptances in custom code. The package intentionally excludes them from version copies. If you write your own duplication logic, replicate that behaviour or you will re-consent users to text they never saw.
• Testing. Cover both branches: user accepted current version, and user accepted only an older version. Add a locale-matrix test for the fallback path — it is the highest-risk area of the release and the easiest to regress.
• When in doubt, read the upgrade guide before the changelog. The changelog lists highlights; docs/upgrading-to-v2.md has the ordered steps, including the config and view review that is easy to skip.