Statamic Editor Api Laravel Package

Getting Started

The Editor API addon exposes an HTTP surface over your Statamic content so the Editor for Drupal & Statamic iOS app (and any client you write against the same contract) can read, create, and update entries without the Control Panel. It is not a general-purpose REST layer — treat it as a purpose-built integration endpoint.

Minimum path to a first edit:

1. composer require ppcharlier/statamic-editor-api on a Statamic v4/v5 site (Statamic's own Laravel constraint governs your PHP/Laravel versions — check it before upgrading either).
2. Publish the config (php artisan vendor:publish) and read config/editor-api.php top to bottom before touching anything else; the collection allow-list and auth settings are the two knobs that decide whether the package does anything at all.
3. Issue a token for a test editor (artisan command or the CP utility, depending on your version) and register the site in the app using the base URL plus that token.
4. Point the app at staging first, restricted to a single sandbox collection with two or three fields. Confirm you can round-trip a draft before you widen the allow-list.
5. On v2.7.0+ there is nothing to buy and no licence key to install — see the licensing trap in Gotchas before you assume that holds for the version you actually have installed.

Where to look first: the package's routes/ file (it tells you exactly which endpoints exist and what middleware wraps them), then the config, then the app's connection screen.

Implementation Patterns

Environment gating. Enable the addon only where you intend it: local off, staging on, production on with a stricter token set. A single EDITOR_API_ENABLED-style flag in .env read by the config keeps a dev machine from ever serving content publicly.

Token per editor, not per site. Issue one token per person or per device so revocation is surgical. Store them as you would any credential — never in the repo, never in a shared note. Rotate on offboarding the same day.

Drafts as the default write path. Have mobile clients create drafts/revisions rather than publishing directly. Editors then review in the CP where the rest of your workflow (approval, publishing schedules, static cache invalidation) already lives. This also caps the blast radius of a bad client build.

Publish, then purge. If you use Statamic's static caching or a CDN, content written via the API will not appear on the front end until you invalidate. Wire a listener on the entry saved/published events to purge the relevant URLs — otherwise you will spend an afternoon debugging "the app saved it but the site is stale."

Field mapping is a contract. Blueprint changes are breaking changes for the app. When you rename, retype, or reorder fields, ship the app-side mapping in the same window. Keep a short changelog of blueprint revisions next to the integration docs.

Asset handling. Route uploads into a dedicated asset container with its own disk and transforms. Mobile photos arrive large and inconsistently oriented; let Statamic's glide/focal-point pipeline normalise them rather than trusting the client.

Test it like an API. Write feature tests that authenticate with a token and assert on the JSON shape for each endpoint you rely on. Pin the package version in CI so an upstream release can't silently change a response key. composer.lock committed, exact-version constraint for this addon specifically.

Cross-CMS parity. Since v2.7.0 the same API contract ships for Drupal 11 (ppcharlier/drupal-editor-api). If your organisation runs both CMSes, build one client-side integration and reuse it — that is the main strategic reason to standardise on this contract.

Gotchas and Tips

The licence is version-dependent, and this is the thing to get right. v2.7.0 and later are MIT. v1.2.3 through v2.6.1 remain commercial — they do not become MIT retroactively. v1.2.2 and earlier were already MIT. Consequences:

• Audit what is actually installed (composer show), not what your composer.json suggests.
• Pin an explicit constraint. A loose ^2.0 that resolves to 2.7.x is fine; a lockfile still on 2.6.1 is not, and you may be running unlicensed.
• Re-run licence scanning in CI after the bump; old approvals referencing the commercial terms should be updated so nobody re-litigates it.
• If you previously had a marketplace licence key or fee-tracking env var, remove it in the same PR that bumps the version. Stale config is a good way to confuse the next person.

The app and the docs were renamed. The iOS client is now Editor for Drupal & Statamic. Update internal runbooks, onboarding docs, App Store links, and any support macros — old references will send people to a dead listing. Nothing functional changes.

Auth failures are ambiguous. A 401 usually means a bad or expired token; a 403 usually means a valid token hitting a collection that isn't in the allow-list. Check the config before you check the token.

Silent no-ops on collections. If a collection returns empty rather than erroring, the allow-list is the first suspect, then blueprint visibility.

Revision bloat. Mobile editing generates revisions faster than CP editing does. Keep the pruning schedule honest, or your database grows faster than you expect.

Debugging. Tail storage/logs/laravel.log with the API channel enabled, and reproduce with curl before blaming the app — the connection screen hides a lot. A php artisan route:list --path=editor (or your prefix) confirms what is actually registered; an addon that appears installed but registers no routes is almost always a cached config or a disabled flag.

Extension points. Rather than editing vendor files, extend via middleware (throttling, logging, IP allow-listing) and event listeners (cache purge, notifications, audit trail). Keep customisations in your own app namespace so a minor bump doesn't wipe them.

Back up before you widen access. The first week of real mobile editing on a production collection is the highest-risk window; take a database snapshot immediately before it.