Organizations Teams Laravel Package

Getting Started

• Install with composer require liberusoftware/organizations-teams. This is a Liberu module package, so check whether Laravel package discovery registers the service provider automatically; if not, add the module/provider to bootstrap/providers.php or config/app.php.
• Publish and run the package assets before writing application code: config, migrations, and any routes/views. Typical flow:
  • php artisan vendor:publish --tag=organizations-teams-config
  • php artisan vendor:publish --tag=organizations-teams-migrations
  • php artisan migrate
  • Confirm published tags in the package README or service provider if the tag names differ.
• Look first at:
  • README.md and composer.json for install and Laravel version constraints.
  • config/ for model overrides, table names, middleware, and context settings.
  • database/migrations/ for the real schema: organizations, teams, memberships, invitations, ownership columns.
  • src/Models/ and src/Contracts/ for the public API.
  • src/Http/Middleware/ and routes for how “current context” is resolved.
  • Any src/Actions/ or src/Services/ classes for create/switch/invite/transfer workflows.
• First use case: create a team, attach the authenticated user as owner, and set it as the current context. Prefer the package’s action/service classes over inserting membership rows directly, because ownership and context invariants are usually enforced there. A day-one smoke test should be:
  1. Create a team.
  2. Add the current user as owner.
  3. Switch into that team.
  4. Assert scoped queries return only that team’s data.
• Because the package has very low adoption, treat the source as the documentation. Read the service provider and the current-context resolver before building screens around it.

Implementation Patterns

• Context middleware: Put the package’s current-team middleware on authenticated web routes after auth. It should resolve the active team from session, route, or user default, bind a context object into the container, and make scoped queries reliable. For API routes, resolve context from a header, token claim, or explicit route parameter instead of session.
• Scoped queries: Use the package’s team-scoping mechanism consistently. Avoid ad-hoc where('team_id', ...) everywhere; centralize it through the context resolver or query scopes. This matters most for dashboards, lists, exports, and search.
• Authorization: Wire team membership and ownership checks into Laravel policies/gates. Day-to-day checks should read like $this->authorize('view', $team) or $user->can('manageMembers', $team), not scattered role-string comparisons. If the package ships policies, register them; otherwise create app-level policies around its models.
• Invitations workflow: Use the package’s invitation creation path, then send your own notification if needed. On accept, validate token + email + expiry, create membership inside a transaction, and dispatch the package’s events so onboarding/listeners run. Rate-limit invite endpoints and clean up expired invitations.
• Ownership changes: Treat ownership transfer and “last owner leaves” as transactional domain operations. Use the package action if present; otherwise wrap membership updates in DB::transaction() and enforce “at least one owner” with a policy plus a database-safe check. Dispatch events after commit.
• Switching teams: Build one switch endpoint that validates membership, updates the session/context, clears any per-team cache keys, and redirects. Do not let clients pass arbitrary team IDs into context without a membership check. After switching, refresh scoped bindings or redirect to a neutral page to avoid stale route-model-bound data.
• Jobs and commands: Never rely on session-based current context in queued jobs, notifications, or artisan commands. Pass a team ID into the job and explicitly run the job inside the package’s context wrapper, or set the context resolver at the start of handle(). This is the main multi-tenant leak risk.
• Integration with auth and UI: Expose the user’s teams and current team through a view composer or Inertia/Livewire shared prop. Use route-model binding with scoped bindings where possible, e.g. resolve teams through the current user’s memberships rather than a global Team::findOrFail().
• Testing pattern: Write feature tests with at least two teams and two users. Assert that user A cannot read team B’s records even with a valid ID, that the last owner cannot be removed, and that switching context changes scoped results. Use RefreshDatabase and run the package migrations in the test suite.

Gotchas and Tips

• Current-context leakage is the biggest risk. Queues, schedulers, CLI commands, and long-running Octane workers do not have a request session. Always set team context explicitly at the boundary and clear it afterward.
• Global scopes can bite: if the package applies a global team scope, console commands and admin reporting may unexpectedly return empty sets. Prefer explicit context wrappers, and provide an escape hatch for cross-team admin queries.
• Last-owner invariant: enforce it in policies, actions, and tests. A database constraint alone is awkward for “at least one owner,” so use a transaction and lock the membership rows if ownership changes are concurrent.
• Invitation edge cases: expired tokens, already-accepted invitations, email mismatch, deleted users, and duplicate memberships. Add unique constraints where appropriate and return generic errors to avoid account enumeration.
• Migration and config publishing: confirm the actual publish tags and provider name from the package. Run php artisan vendor:publish interactively once, then codify the tags. Clear config cache after changes: php artisan config:clear.
• Middleware order: auth must run before context resolution, and context must run before policies/scoped bindings. A misordered middleware stack often shows up as “works in controller, fails in route model binding.”
• Route model binding: avoid binding a team by ID globally. Scope bindings to the current user’s memberships or current context; otherwise a valid ID from another team can leak existence or data.
• Package maturity: 0 stars and 0 dependents means you are an early adopter. Pin the version in composer.json, read the source for the actual method names, and write integration tests around the flows you depend on. The listed last-release date appears ahead of the current date, so verify tags/releases before assuming stability.
• Extension points to use: config-based model overrides, package events/listeners, policies, custom middleware for context resolution, and action/service classes. Prefer these over forking the package.
• Debugging checklist:
  • Confirm the context object is bound: inspect the container binding in Tinker.
  • Log team_id on scoped queries during development.
  • Use php artisan route:list to verify package routes and middleware.
  • Use php artisan migrate:status to confirm package migrations ran.
  • In tests, dump the resolved current team before asserting scoped results.