Collaboration Laravel Package

Getting Started

This is a Statamic Pro control-panel addon, not a general-purpose Laravel package. Your first task is a prerequisite audit, not writing code — there is no meaningful integration path in a stock Laravel app.

Before composer require, confirm:

• Statamic Pro license — hard requirement, not negotiable.
• A broadcast stack you can operate. Laravel Reverb (self-hosted), Pusher, or Ably. Verify the current supported driver list against the published config; the broadcasting layer is the hidden cost that kills pilots.
• Pinned constraints. There is no broadly published compatibility matrix. Treat composer.json as the contract and pin statamic/collaboration >=2.0.1 if you run multi-site (#115 is the fix).

Minimal install:

composer require statamic/collaboration
php artisan vendor:publish --tag=collaboration-config   # verify actual tag against docs

Wire broadcasting (Reverb example):

BROADCAST_CONNECTION=reverb
REVERB_APP_ID=local
REVERB_APP_KEY=local
REVERB_APP_SECRET=local
REVERB_HOST=localhost
REVERB_PORT=8080
REVERB_SCHEME=http

php artisan install:broadcasting   # or wire Echo/pusher-js by hand
php artisan reverb:start
npm run dev

Read in this order:

1. The published config/collaboration.php. It is usually a more accurate statement of behavior than the README — enablement flags, per-collection/per-site toggles, polling vs. broadcast driver selection all live here.
2. Channel authorization in routes/ and src/. This is where presence maps to Statamic users and permissions, and the thing that bites you in a multi-role install.
3. release/v2.0.1.md. Tiny but load-bearing: multi-site fix (#115), improved debugging (#114), UI polish (#112). The debugging improvement is your first tool during the spike.

First use case — the two-window test. Open the same entry as two different Statamic users in two browsers (not two incognito tabs of one user) and confirm:

• presence indicators appear for both,
• the "someone else is editing" warning fires,
• closing one tab clears presence in the other within a reasonable window,
• stopping Reverb degrades gracefully rather than hard-erroring in the CP.

That single test exercises roughly 80% of what goes wrong in production. Run it on a multi-site tree in staging, not a single-site install — multi-site is the known defect domain.

Implementation Patterns

Config-gated rollout, never a global switch-on. Ship behind an env-driven flag so you can disable with a config flip instead of a rollback:

// config/collaboration.php (shape illustrative — verify keys against published file)
'enabled' => env('COLLABORATION_ENABLED', false),

Ship to staging → one collection → one site → all editors.

Treat multi-site as a first-class scenario. v2.0.1 fixes it (#115), but a fix is not a proven matrix. Regression-test your own topology per site:

- site A: two editors, same entry, same locale
- site B: same entry handle, different locale, different editors
- cross-site: editor in A opens an entry also open in B

Operate Reverb as a supervised service. The addon ships presence, not websocket uptime. Give the broadcast server a Supervisor/systemd unit, process monitoring, and a documented restart procedure. Pusher/Ably instead? That becomes a vendor SLA line item — money traded for ops burden, a legitimate choice.

Local dev hygiene. Point BROADCAST_CONNECTION at a local Reverb instance alongside npm run dev. Never let developer machines attach to the shared production Pusher app — presence state cross-contaminates and produces phantom collaborators that are near-impossible to reason about.

Debugging workflow. The 2.0.1 debugging output (#114) targets presence/reconnect diagnosis. Read it before reaching for Redis or Echo inspection. Presence ghosting is almost always one of: (a) a disconnected client that hasn't timed out, (b) channel auth silently returning 403, or (c) a reverse proxy terminating the websocket upgrade.

Testing. Presence is timing-sensitive and browser-level — unit tests won't touch the failure modes that matter. Automate the two-window scenario with Dusk or Playwright against a staging build with two authenticated sessions, and assert on the visible presence affordance, not internal state.

CSP and proxy first, app layer second. Websockets are routinely blocked by connect-src and by proxies that don't forward the Upgrade header. Add your Reverb/Pusher host to connect-src and confirm proxy_set_header Upgrade / Connection "upgrade" before debugging the app. Half of "collaboration is broken" reports live in infra.

Custom fieldtypes. If you run Bard/ProseMirror customizations or bespoke fieldtypes, treat CP surface compatibility as undocumented and scope a validation pass as its own task.

Recommended sequencing:

1. License/procurement check.
2. Confirm 2.x baseline (1.x → 2.x is its own work item).
3. Stand up broadcasting + security controls (TLS, auth, CSP).
4. Staging install + role/permission mapping + dedicated multi-site pass.
5. Bounded pilot with representative editors.
6. Define rollback and degraded-mode behavior.
7. Progressive rollout.

Gotchas and Tips

Pin >=2.0.1 for multi-site. #115 is the single most relevant fix for real deployments. Before 2.0.1, multi-site was a stated target with a known defect — disqualifying. On 2.0.1+, it becomes a scenario to validate, not a reason to exclude.

v2.0.1 is a patch, not a capability release. UI polish, debugging, multi-site fix. No breaking changes, no new features. Don't let it move your adopt/pilot decision — it removes one known defect and nothing more. Equally, don't read it as evidence of mature release cadence; 36 stars and 0 dependents is still a thin adoption signal.

Provenance is why you trust it, not popularity. Authored by @jackmcdade and @jasonvarga — Statamic core maintainers. That shifts support from community-first to vendor-first. Practical consequence: there is almost no public troubleshooting trail. When something breaks, you will not find a Stack Overflow answer; you escalate. Budget for that in on-call.

Flat-file concurrency is the sharp edge. Statamic stores content as flat files. On shared/NFS/network storage, file-level locking semantics are unreliable. Validate simultaneous saves against the storage you will actually run in production, not your local SSD. This is the most likely source of data loss and the one thing the addon cannot fully insulate you from.

Know the concurrency model. The promise is presence and editing awareness — not hard locking, not character-level co-editing. Confirm explicitly before you sell "co-editing" to stakeholders, and test simultaneous-save behavior to document the actual failure mode.

Stale presence / ghosting. Expect presence to linger after a hard disconnect until timeout. Two consequences: editors will see occasional phantom collaborators (document it or eat tickets), and you should not build automation (auto-save gates, publish blocks) on presence state until you have measured the staleness window empirically.

Test websocket unavailability; don't assume it. Stop Reverb and open the CP. Does the editor degrade to plain Statamic with a quiet error, or break outright? If it hard-fails, you need a config-level kill switch wired to a health check.

Config caching. After changing config/collaboration.php or broadcast settings, run php artisan config:clear (and config:cache in production). A stale cache pointing at the wrong broadcast driver is the classic "presence just stopped working."

Channel authorization ≠ Statamic permissions. Verify presence channels actually use Statamic's permission model. A mismatch means users without edit rights can still see who is editing an entry, or worse, presence attaches to the wrong entry across sites. Read the authorization code path; don't assume it inherits from the CP.

Validate the last-release date (2026-04-27) against the repo's real release history and compatibility matrix. A future-dated release in metadata is your cue to check provenance and cadence directly rather than trust the feed.

1.x users: the 2.x boundary is real. Treat the upgrade as a discrete work item with its own test pass. If the upgrade path isn't documented, that's a scoping risk, not a footnote.

Extension points are limited. This is a closed, opinionated CP feature. If your real gap is approvals, audit trails, or granular permissions, this package does not solve it, and extending it to do so is a build project wearing a vendor costume. Buy it for presence; build workflow elsewhere.

Put kill criteria in the ticket, not the retro. Define them before the pilot: no measurable drop in overwritten-revision incidents after 60 days, or websocket ops burden exceeding the collaboration value. A config-flag rollback makes the kill cheap — that is the main architectural insurance you get here.