Statamic Uuid Laravel Package

Getting Started

v2.4.0 is a small release in terms of surface area — a single PR adding Statamic v6 compatibility — but it is the release that moves the addon onto a new major version of the host CMS. Start there.

1. Check your host version before anything else. The meaningful change is the statamic/cms constraint in composer.json. On Statamic 5 you stay on ^2.3; only move to ^2.4 once the site itself is on Statamic 6.
2. Install and publish config with the usual addon flow (composer require aryehraber/statamic-uuid, then publish the config tag listed in the README). Read the README's fieldtype/config section first — the addon's whole API is essentially "one fieldtype plus a small config file."
3. Read src/ServiceProvider.php and the fieldtype class before the docs. The behaviour you care about (when a UUID is generated, and whether an existing one is preserved) lives in the save/fieldtype lifecycle, not in configuration.
4. First use case: add the UUID field to a single collection's blueprint, create an entry in the Control Panel, save, and confirm a value appears in the entry's front-end output and in the raw file. Then save the entry again and confirm the value did not change. That second assertion is the one that matters — a UUID that regenerates on every save is worse than no UUID at all.

Implementation Patterns

Stable external identifiers. The core pattern is exposing an opaque, immutable ID to systems outside Statamic: webhooks, a mobile app, a CRM sync, JSON-LD @id, or analytics events. Keep Statamic's internal entry id internal and hand the UUID to consumers, so content restructuring (renaming collections, re-slugging, moving entries between trees) doesn't break external references.

Add to the blueprint deliberately. UUIDs are useful on collections that are read by external systems, not on every collection. Add the field per-blueprint rather than assuming a global setting, and set visibility so it renders in the publish form but isn't casually editable.

Templates. In Antlers/Blade it's just a field: {{ uuid }}. Common uses are <section id="{{ uuid }}"> for permalinkable blocks, stable keys in a JSON feed, and data-uuid attributes for client-side tracking that survive slug changes.

Ingestion and imports. When content arrives from an API or a CSV, generate/preserve the UUID at creation time in your importer rather than relying on an editor to save the entry later. Store the source system's key alongside it so re-imports are idempotent (look up by UUID, then update, rather than creating duplicates).

Backfilling existing content. For a collection that predates the field, expect to backfill. The reliable pattern is a one-off command that iterates entries, checks for an empty UUID, and saves each one — followed by php artisan statamic:stache:clear. Test on a copy of the content directory first; this is a write to every entry file.

Testing. Add the UUID field to your test blueprints/fixtures so factories and seeders produce it. Assertions on generated UUIDs should check format and stability, not a hard-coded value.

Gotchas and Tips

• This is a minor version doing a major thing. The changelog is one line — "Statamic v6" — with no breaking-change notes. Treat the 2.3 → 2.4 bump as requiring a regression pass, especially around entry creation, replication, and multisite, even though semver calls it non-breaking.
• Upgrade ordering is the real risk. Statamic 6 requires PHP 8.2+ and its own addon ecosystem alignment. If any other addon in the project isn't v6-ready, pin aryehraber/statamic-uuid to ^2.3 and defer. Conversely, don't upgrade this addon on a Statamic 5 site — the constraint will fight you.
• Duplication and multisite are the classic failure modes. Verify what happens when an entry is duplicated in the Control Panel and when a multisite site localises an existing entry: you want a fresh UUID for a copy, and a clear (documented) rule for localisations. Test both explicitly after the upgrade rather than assuming.
• Never regenerate on update. If you see UUIDs changing on re-save, the generation is wired to the wrong lifecycle hook (or the field is being overwritten by an importer). Reproduce, read the fieldtype's preprocess/save methods, and fix at source rather than papering over it.
• Protect against editor edits. A hand-edited UUID silently breaks every external reference. Use the blueprint's read-only option, or at minimum a validation rule enforcing UUID format.
• Uniqueness is on you. The addon generates values; it doesn't necessarily guarantee a unique index. Enforce format/uniqueness in validation and consider a stache query or a periodic consistency check if UUIDs feed an external system.
• Debugging order: field present in blueprint → field present in the saved content file → value rendered in the template. php artisan statamic:stache:clear after any direct file manipulation, config change, or backfill; stale stache explains most "the UUID is there but the site doesn't see it" reports.
• Extension points are thin. This is a deliberately small addon, so resist forking it. If you need custom generation logic, wrap it in your own listener/fieldtype rather than patching vendor code, so future Statamic major bumps stay a composer update.