Statamic Community Laravel Package

Getting Started

• Install: composer require <vendor>/<package>:^0.1.1. This release exists specifically to make that possible — v0.1.0 declared goldnead/statamic-teams as a dev branch requirement and forced minimum-stability: dev, so it could never be resolved from Packagist. On v0.1.1 the constraint is ^0.4 and stability is stable, so a normal install now works.
• Confirm the baseline first: you need a Statamic project with goldnead/statamic-teams ^0.4 installed and its teams/migrations published before this package will boot. If you already run a different Teams version, resolve that mismatch before debugging anything else — Composer will either block the install or you'll get runtime failures on missing classes.
• Where to look first: the package's service provider (addon registration + bindings), its published config file, and any routes/middleware it registers. In a Statamic addon, the config file and the Statamic::booted() / AddonServiceProvider hooks tell you more about real behaviour than the README usually does.
• First use case: scope a resource to a team and prove isolation end-to-end — a user in Team A lists/views only Team A's records, and gets a 403/404 on Team B's record ID. Do this before building features; it validates config, middleware, and policy wiring in one pass.

Implementation Patterns

• Establish the current-team context early. Typical pattern: middleware resolves the team (route parameter, session, or user's default team) and binds it into the container/request; downstream code reads it instead of re-deriving it. Keep a single source of truth so controllers, policies, and views can't disagree.
• Layer authorization, don't replace it. Statamic Teams handles membership/roles; your app's policies and gates should still be the enforcement point. A policy like "user belongs to this record's team AND holds the required team role" is the safe composition.
• Query scoping: apply team constraints at the query level (a global scope, a repository method, or an explicit where on the team foreign key) rather than filtering in the UI. UI-only filtering is the most common way multi-tenant data leaks.
• Route model binding: scope bindings to the current team so cross-team IDs fail naturally, e.g. resolve through a team-scoped relationship rather than Model::findOrFail().
• Statamic/Antlers integration: expose team data through a tag, view composer, or fieldtype rather than reaching into models in templates. For CP customisation, hook into the nav/permissions the Teams addon already publishes.
• Testing: use RefreshDatabase, create two teams with one user each, and assert the negative case (Team B access returns 403/404). This suite is your regression net for a 0.1.x dependency.
• Queues, commands, scheduled jobs: pass an explicit team ID into the job and re-bind it inside handle(). Anything without a request has no session team and will silently read unscoped data.

Gotchas and Tips

• The 0.1.0 trap: if you pinned 0.1.0 or vendored it, you were relying on a dev-branch requirement. Upgrading to 0.1.1 changes your dependency graph (^0.4, stable) — run composer update and re-check the lock file rather than assuming a no-op patch.
• minimum-stability side effects: projects that lowered minimum-stability to dev to work around 0.1.0 should raise it back to stable once on 0.1.1, or you'll keep pulling unstable transitive packages.
• Pre-1.0 API churn: treat 0.1.x as unstable. Pin exact versions (0.1.1, not ^0.1) until you've read a changelog, and re-run your isolation tests after every bump.
• Stache/config caching: after changing addon config or blueprints, clear Statamic's caches (php artisan statamic:stache:clear, plus config:clear). Stale Stache is the usual cause of "my config change did nothing".
• Session-based team context breaks silently for API routes, webhooks, and console commands. Always have an explicit override path for setting the current team.
• Multi-site + teams compounds: team scoping and site scoping are orthogonal. Decide the precedence rule (team-then-site is typical) and encode it once, or you'll get inconsistent results between CP and front end.
• Debugging checklist for "user sees nothing": Teams version constraint satisfied → config published → middleware in the right group → user actually attached to a team → team ID column populated on existing records (migrations don't backfill).