Statamic Delegated Laravel Package

Getting Started

Delegated is a Statamic add-on (installable into a Laravel app) that layers scoped editorial access on top of Statamic's own permissions: users are confined to territories, work is handed around through assignments, and every change of hands is recorded in an audit log.

Minimal path from zero:

1. composer require the package. As of v1.0.2 the Statamic constraint is >=6.31.0 <6.39.0, so a brand-new site that pulled Statamic 6.38 no longer needs a downgrade to install.
2. Publish and run the package's migrations (it needs its own tables for territories, assignments and the audit log). Nothing is stored in Statamic's own content tables.
3. Publish the package config and read it top to bottom before touching the control panel — it is the map of the whole feature set: which collections/entries are delegatable, what a territory is keyed on, who may assign to whom, and whether the audit log is on by default.
4. Give a role the package's permissions in Users → Roles. Delegated does not replace Statamic permissions; it narrows them, so a user still needs ordinary edit rights on the collection before a territory can restrict them further.
5. First real use case: create one territory, drop a single editor into it, log in as that editor and confirm they see only their slice of the content tree. Then make an assignment to a second user and check the audit log entry appears.

Where to look first when something behaves unexpectedly: the published config, then the permission definitions in the service provider, then the audit log — it usually tells you who did what and under which territory.

Implementation Patterns

Territory as the unit of scoping. Model territories around whatever your editors actually think in — a region, a brand, a market — not around site handles. Multi-site and territories are orthogonal: a territory may span sites, and a site may contain many territories. Keep the mapping explicit in config so it is reviewable in a diff rather than buried in the database.

Assignment as a hand-off, not a permission. Assignments route work to a person; territories decide what they can see. Keeping those two ideas separate makes both easier to reason about — you can reassign a piece of work without re-scoping anyone's access, and re-scope someone without silently stealing their queue.

Treat the audit log as an append-only compliance artifact. Read it through the package's query surface for reporting and dashboards; do not write to it, and do not let it become a general activity feed. If you need product analytics, emit your own events alongside it.

Seed in code, assign in the UI. Territories and the config-level wiring belong in seeders or a deploy step so environments stay reproducible. Actual day-to-day assignments should be made by editors in the control panel, because that is the action the audit log exists to record.

Test at the boundary. Statamic's testing helpers let you act as a user and assert what the control panel exposes. Assert the negative case — that a user in territory A cannot see or edit territory B's entries — rather than only asserting the happy path. That is the regression you actually care about.

CI and deploys. Pin the Statamic constraint in composer.json and let Dependabot/Renovate surface new 6.x minors; the addon's own range is intentionally narrow (see Gotchas). The control-panel assets ship prebuilt in the package, so a front-end build step is not part of your pipeline — but a stale published asset bundle in public/vendor is, so include the vendor publish in your deploy recipe.

Upgrades are cheap by design. v1.0.2 is a compatibility release: same restrictions, same behaviour, no migration, territories/assignments/audit log untouched. Budget upgrades as routine composer update work unless the notes say otherwise.

Gotchas and Tips

• The Statamic ceiling moves before the addon does. The constraint <6.39.0 means the day Statamic 6.39 ships, composer update on a site using Delegated will fail to resolve until a matching addon release lands. Know this in advance and pin Statamic to a known-good minor on production sites, or upgrade Statamic deliberately rather than incidentally.
• A fresh install on the newest Statamic was the actual bug being fixed here. Before v1.0.2 the constraint excluded 6.38, so composer require on a new site failed or forced a downgrade. If you hit "your requirements could not be resolved" on a new project, check the addon version first — you want 1.0.2 or later.
• "No migration needed" applies to upgrading, not installing. A first install still needs the migrations run; do not read the 1.0.2 note as "this package has no schema."
• Delegated narrows, it does not grant. A user with no Statamic edit permission on a collection gets nothing from a territory. When access looks wrong, check Statamic's role permissions before you check territories — the addon is the second place to look, not the first.
• Super users bypass restrictions. Statamic's super-user flag is an escape hatch that will make territory scoping appear broken during testing. Always test as a non-super user, or you will conclude the feature is a no-op.
• Control-panel asset caching. The bundle was rebuilt for 6.38 with no functional change, but browsers and public/vendor both cache aggressively. After any addon upgrade, re-publish the assets and hard-reload before filing a UI bug.
• Don't prune or rewrite the audit log. It is the reason the package exists in a regulated context. If you need retention limits, implement them as archival copies, not deletes, and decide that before you have a year of history.
• Extension points are config-first. Before forking, check whether the behaviour you want is already a config toggle — territory keys, assignment rules and audit verbosity are the usual knobs. Forking a permission layer is a permanent maintenance tax, and this package's release cadence is currently tied to Statamic's minor releases.
• Version skew in a team. Because the addon's supported range is narrow, two developers can end up on different Statamic minors with different lockfiles. Commit composer.lock for the CMS itself and treat Statamic upgrades as a reviewed change, not a side effect of composer update.