Skip to content

Teams

View raw .md
On this page

Introduction#

Team management is a feature-gated module. All team routes and logic are only registered when the teams feature is enabled:

php
// config/magic-starter.php
'features' => [
    Features::teams(),
],

All team endpoints require auth:sanctum middleware. Routes are handled by TeamController, TeamMemberController, TeamInvitationController, and TeamPhotoController.


Team CRUD#

List Teams#

text
GET /teams

Returns a paginated list of all teams the authenticated user owns or belongs to, ordered by name.

Query Parameters:

Parameter Type Default Description
per_page integer 15 Items per page (max 100)

Response: 200 OK

json
{
  "data": [
    {
      "id": "9a8b7c6d-...",
      "name": "Acme Corp",
      "personal_team": false,
      "owner_id": "1a2b3c4d-...",
      "user_role": "owner",
      "profile_photo_url": "https://...",
      "created_at": "2026-01-15T10:30:00.000000Z",
      "updated_at": "2026-01-15T10:30:00.000000Z"
    }
  ],
  "links": { "..." : "..." },
  "meta": { "..." : "..." }
}

Controller: TeamController@index


Create Team#

text
POST /teams

Creates a new team. The authenticated user becomes the owner.

Request Body:

Field Type Rules
name string required, string, max:255

Response: 201 Created

json
{
  "data": {
    "id": "9a8b7c6d-...",
    "name": "New Team",
    "personal_team": false,
    "owner_id": "1a2b3c4d-...",
    "user_role": "owner",
    "profile_photo_url": null,
    "created_at": "2026-03-25T12:00:00.000000Z",
    "updated_at": "2026-03-25T12:00:00.000000Z"
  }
}

Contract: CreatesTeams (overridable via service container binding)

Controller: TeamController@store


Show Team#

text
GET /teams/{team}

Returns a single team. Requires view policy authorization (user must belong to the team).

Response: 200 OK

json
{
  "data": {
    "id": "9a8b7c6d-...",
    "name": "Acme Corp",
    "personal_team": false,
    "owner_id": "1a2b3c4d-...",
    "user_role": "admin",
    "profile_photo_url": "https://...",
    "created_at": "2026-01-15T10:30:00.000000Z",
    "updated_at": "2026-01-15T10:30:00.000000Z"
  }
}

Controller: TeamController@show


Update Team#

text
PUT /teams/{team}

Updates team details. Requires update policy authorization (owner only).

Request Body:

Field Type Rules
name string required, string, max:255
photo file nullable, image, max:1024 KB

Response: 200 OK -- returns updated TeamResource.

Contract: UpdatesTeams (overridable via service container binding)

Controller: TeamController@update


Delete Team#

text
DELETE /teams/{team}

Deletes the team. Requires delete policy authorization (owner only). Personal teams cannot be deleted -- returns a 422 validation error.

If the deleted team was the user's current active team, the user is automatically switched to their next available team.

Response: 200 OK

json
{
  "data": null,
  "message": "Team deleted successfully."
}

Error (personal team): 422 Unprocessable Entity

json
{
  "message": "You may not delete your personal team.",
  "errors": {
    "team": ["You may not delete your personal team."]
  }
}

Contract: DeletesTeams (overridable via service container binding)

Controller: TeamController@destroy

With the restorable delete on, this endpoint trashes the team instead and answers with the end of its restore window:

json
{
  "data": {
    "restore_until": "2026-11-28T12:00:00.000000Z"
  },
  "message": "Team deleted. Its owner can restore it until the restore window closes."
}

The same refusals apply, including the subscription guard, and the contract is TrashesTeams.


Restore Team#

text
POST /teams/{team}/restore

Registered only with the restorable delete on. Brings a trashed team back. Requires restore policy authorization (owner only). This is the one endpoint that finds a trashed team; every other team endpoint answers 404 for it.

Restoring a team that is already live changes nothing and answers 200, so a client that sends the request twice is not punished.

Response: 200 OK -- returns the TeamResource with a message.

Error (window closed): 422 Unprocessable Entity

json
{
  "message": "This team can no longer be restored.",
  "errors": {
    "team": ["This team can no longer be restored."]
  }
}

Contract: TrashesTeams (overridable via service container binding)

Controller: TeamController@restore


Restorable Delete#

By default DELETE /teams/{team} deletes the team for good. The restorable-teams feature makes that delete reversible: the team is hidden for a window, its owner can restore it, and a scheduled command deletes it once the window has closed. It is off until you switch it on, and while it is off nothing about team deletion changes.

Switching it on takes three things in the consuming application:

  1. The column. magic-starter:install publishes add_soft_deletes_to_teams_table with the teams feature; on an existing install copy it from vendor/fluttersdk/magic-starter-laravel/database/migrations/ into database/migrations/. It adds deleted_at and an indexed, nullable restore_until.
  2. The trait. The team model uses Illuminate\Database\Eloquent\SoftDeletes. The published App\Models\Team stub does; add it by hand to an older one. The package's own Models\Team does not, so that applications that never opt in keep a teams table without the column.
  3. The feature and the schedule.
php
// config/magic-starter.php
'features' => [
    \FlutterSdk\MagicStarter\Features::teams(),
    \FlutterSdk\MagicStarter\Features::restorableTeams(),
],

'teams' => [
    'restore_days' => 30, // MAGIC_STARTER_TEAM_RESTORE_DAYS
],
php
// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('magic-starter:purge-trashed-teams')->daily();

The package registers the command and does not schedule it. Without the schedule line a trashed team is never deleted.

What a trash does#

TrashesTeams::trash() runs in one transaction:

  1. clears current_team_id for every user whose active team is this one, with a query-builder update that ignores $fillable. A soft delete is an update and never triggers the foreign key's nullOnDelete, so without this the pointer would name a team nobody can see;
  2. cancels the pending invitations, because a link to a hidden team must not be acceptable;
  3. writes restore_until, teams.restore_days days from now (0 closes the window at once);
  4. soft deletes the team.

Members stay attached, so a restore brings the team back with the people it had. The team disappears from GET /teams and from every relation, because the model's soft delete scope hides it. A restore does not put the pointers back (they are each person's choice, and they have been somewhere else since) and does not bring the invitations back; the owner invites again.

The subscription guard of the plain delete applies to a trash as well (Actions\SubscriptionGuardedTrashTeam), so a team a store or Stripe is still billing is refused with the same sentence.

What a restore does#

TrashesTeams::restore() clears deleted_at and restore_until in one write, and refuses with a 422 once restore_until is not in the future. A trashed team with no restore_until (trashed by other means) has no window to close and is restored.

The purge#

bash
php artisan magic-starter:purge-trashed-teams

Selects the trashed teams whose restore_until is not in the future and deletes each through DeletesTeams, so the subscription guard and the photo cleanup run as they do for any team. DeletesTeams is the purge: on a model that soft deletes it force deletes. Each team is read again under a lock first, so a restore that lands after the walk loaded it wins.

Outcome Meaning
Deleted Removed with its photo, memberships and invitations.
Held The billing guard refused. Logged as well as printed, left trashed, and tried again on the next run.
Restored Its owner restored it after the walk loaded it. Skipped.
Failed Reported, and the run moves on. The exit code is non-zero.
text
Purge finished: 12 deleted, 1 held, 0 restored, 0 failed.

A team model that does not use SoftDeletes, or a table without restore_until, has nothing to purge and the command says so.

Account deletion#

An account purge deletes the teams the user trashed too, for good and through DeletesTeams: OwnedTeams::includingTrashed() reads them, and a trashed team a subscription still bills holds the purge back like any other. A trashed team does not count as a shared team, so it never blocks scheduling the deletion.


Team Members#

List Members#

text
GET /teams/{team}/members

Returns all members of the team, including the owner. The owner is injected with the owner role. Requires view policy authorization.

Response: 200 OK

json
{
  "data": [
    {
      "id": "1a2b3c4d-...",
      "name": "John Doe",
      "email": "[email protected]",
      "profile_photo_url": "https://...",
      "role": "owner"
    },
    {
      "id": "5e6f7g8h-...",
      "name": "Jane Smith",
      "email": "[email protected]",
      "profile_photo_url": "https://...",
      "role": "admin"
    }
  ]
}

Controller: TeamMemberController@index


Update Member Role#

text
PUT /teams/{team}/members/{user}

Updates a team member's role. Requires manageMembers policy authorization (owner or admin). Cannot change the role of the team owner (returns 403).

Request Body:

Field Type Rules
role string required, string, in:admin,editor,member

Response: 200 OK

json
{
  "message": "Team member updated successfully."
}

Error (changing owner role): 403 Forbidden

text
Cannot change role of team owner.

Controller: TeamMemberController@update


Remove Member#

text
DELETE /teams/{team}/members/{user}

Removes a member from the team. Requires manageMembers policy authorization (owner or admin). Cannot remove the team owner (returns 403).

If the removed member's current_team_id points at this team, it is cleared, so their next read lands on their personal team instead of the team they were removed from. A member whose current team is another team keeps it.

Response: 200 OK

json
{
  "message": "Team member removed successfully."
}

Error (removing owner): 403 Forbidden

text
Cannot remove team owner.

Contract: RemovesTeamMembers (overridable via service container binding)

Controller: TeamMemberController@destroy


Leave Team#

text
DELETE /teams/{team}/leave

Allows the authenticated user to leave a team. The team owner cannot leave (returns 403). If the user is not a member, returns 404.

If the team being left was the user's current active team, current_team_id is cleared and the user falls back to their personal team (getCurrentTeamOrPersonal()). A user whose current team is another team keeps it.

Response: 200 OK

json
{
  "message": "You have left the team."
}

Error (owner leaving): 403 Forbidden

text
Team owner cannot leave the team. Delete the team instead.

On the owner's personal team, which cannot be deleted either:

text
You may not leave your personal team.

Error (not a member): 404 Not Found

text
You are not a member of this team.

Contract: RemovesTeamMembers

Controller: TeamMemberController@leave


Team Invitations#

List Invitations#

text
GET /teams/{team}/invitations

Returns a paginated list of pending invitations for the team, ordered by most recent. Requires manageInvitations policy authorization (owner or admin).

Query Parameters:

Parameter Type Default Description
per_page integer 15 Items per page (max 100)

Response: 200 OK

json
{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "team_id": "9a8b7c6d-...",
      "email": "[email protected]",
      "role": "member",
      "token": "abc123def456...",
      "created_at": "2026-03-25T12:00:00.000000Z",
      "updated_at": "2026-03-25T12:00:00.000000Z"
    }
  ],
  "links": { "..." : "..." },
  "meta": { "..." : "..." }
}

Controller: TeamInvitationController@index


Create Invitation#

text
POST /teams/{team}/invitations

Sends a team invitation to an email address. Requires manageInvitations policy authorization. Returns 422 if an invitation already exists for that email or the user is already a team member.

Request Body:

Field Type Rules
email string required, email, max:255
role string required, string, in:admin,editor,member

Response: 201 Created

json
{
  "data": {
    "id": "a1b2c3d4-...",
    "team_id": "9a8b7c6d-...",
    "email": "[email protected]",
    "role": "member",
    "token": "abc123def456...",
    "created_at": "2026-03-25T12:00:00.000000Z",
    "updated_at": "2026-03-25T12:00:00.000000Z"
  }
}

Error (duplicate invitation): 422 Unprocessable Entity

json
{
  "message": "An invitation has already been sent to this email.",
  "errors": {
    "email": ["An invitation has already been sent to this email."]
  }
}

Error (already a member): 422 Unprocessable Entity

json
{
  "message": "This user is already a member of the team.",
  "errors": {
    "email": ["This user is already a member of the team."]
  }
}

Contract: InvitesTeamMembers (overridable via service container binding)

Controller: TeamInvitationController@store


Cancel Invitation#

text
DELETE /teams/{team}/invitations/{invitation}

Cancels (deletes) a pending invitation. Requires manageInvitations policy authorization. The invitation must belong to the specified team (returns 404 otherwise).

Response: 200 OK

json
{
  "data": null,
  "message": "Invitation canceled successfully."
}

Controller: TeamInvitationController@destroy


Accept Invitation#

text
POST /invitations/{token}/accept

Accepts a team invitation using a token. The authenticated user's email must match the invitation email (case-insensitive). Expired invitations return 410 Gone and are automatically deleted.

If the user is already a member, the invitation is deleted and a success message is returned.

Response: 200 OK

json
{
  "data": null,
  "message": "Invitation accepted. You have joined the team."
}

Error (email mismatch): 403 Forbidden

json
{
  "message": "This invitation was sent to a different email address."
}

Error (expired): 410 Gone

json
{
  "message": "This invitation has expired."
}

Confirming a different email (opt-in): Sign in with Apple can hand the app a private relay address (@privaterelay.appleid.com), so someone invited at their real address can never match. Set invitation_confirm_email_mismatch (MAGIC_STARTER_INVITATION_CONFIRM_EMAIL_MISMATCH, off by default) and a user who may confirm is asked first instead of refused. They may confirm when they hold a Sign in with Apple link that has not been revoked, or their address is on privaterelay.appleid.com (the whole domain, case-insensitive). Everyone else keeps the 403 above, whatever the request carries.

409 Conflict, with nothing attached and the invitation left in place:

json
{
  "message": "This invitation was sent to a different email address. Confirm to join with this account.",
  "code": "email_mismatch",
  "requires_confirmation": true,
  "masked_email": "a***@example.com"
}

masked_email is the invited address reduced to its first character and its domain, for the client to show. Repeat the request with {"confirm_email_mismatch": true} to join; only a true value confirms. The repeat goes through AcceptsTeamInvitations like any other accept, so the expiry, already-a-member and ensureCanJoin() checks all still run, and the token is used up by the join. The invitation token is the proof that the person was invited: anyone holding the link and an Apple account can use this, which is why it is off by default.

Controller: TeamInvitationController@accept


Team Photos#

Team photo endpoints are only available when both teams and profile-photos features are enabled.

Upload Team Photo#

text
POST /teams/{team}/profile-photo

Uploads or replaces the team's profile photo. Requires update policy authorization (owner only). The previous photo is deleted from disk before storing the new one.

Request Body: multipart/form-data

Field Type Rules
photo file required, image, max:2048 KB

Response: 200 OK -- returns updated TeamResource.

The photo is stored using the disk configured in magic-starter.team_photo_disk (falls back to magic-starter.profile_photo_disk, then filesystems.default). The storage path is configured via magic-starter.team_photo_path (default: team-photos).

Controller: TeamPhotoController@update


Delete Team Photo#

text
DELETE /teams/{team}/profile-photo

Removes the team's profile photo. Requires update policy authorization (owner only). The photo file is deleted from disk and profile_photo_path is set to null. profile_photo_url answers null again, and the client draws its own placeholder.

Response: 200 OK -- returns updated TeamResource.

Controller: TeamPhotoController@delete


Switch Current Team#

text
PUT /user/current-team

Switches the authenticated user's active team. The request is authorized via the switchTo policy gate (user must belong to the team).

Request Body:

Field Type Rules
team_id string required, uuid, exists in teams table

Response: 200 OK

json
{
  "data": { "...UserResource..." },
  "message": "Team switched successfully"
}

Error (not a member): 403 Forbidden

json
{
  "message": "You are not a member of this team."
}

Request: SwitchTeamRequest (authorization is handled in the request's authorize() method via Gate::allows('switchTo', $team))

Controller: AuthController@switchTeam


Lifecycle Events#

A host that tells people when something happens to their team (a member joined, the household was deleted, ownership passed) listens to six events instead of overriding the actions:

Event Dispatched Properties
Events\TeamMemberJoined After a member is attached: an invitation accepted (AcceptTeamInvitation) or a user added by email (AddTeamMember). teamId, userId, actorId (the joiner when they accepted, the user who added them otherwise)
Events\TeamMemberRemoved After a member is detached by RemoveTeamMember, which serves both the remove and the leave endpoints. teamId, userId, actorId (equal to userId when the member left)
Events\TeamDeleted After a team is deleted for good by DeleteTeam: the delete endpoint with the restorable delete off, magic-starter:purge-trashed-teams, the admin panel, and the account purge for each team the user owned. teamId, ownerId, memberIds (everyone who belonged, the owner included, in no particular order)
Events\TeamTrashed After TrashTeam hides a team for its restore window. teamId
Events\TeamRestored After TrashTeam brings a trashed team back inside the window. teamId
Events\TeamOwnershipTransferred After TransferTeamOwnership hands a team to another member: a host's own transfer, the admin panel, and the account purge when it hands on a departing owner's team. teamId, previousOwnerId, newOwnerId, actorId
php
use FlutterSdk\MagicStarter\Events\TeamDeleted;
use FlutterSdk\MagicStarter\Events\TeamMemberJoined;
use Illuminate\Support\Facades\Event;

Event::listen(TeamMemberJoined::class, fn (TeamMemberJoined $event) => /* tell the owner */);
Event::listen(TeamDeleted::class, fn (TeamDeleted $event) => /* tell every former member */);

Four rules hold for all six:

  • After the commit. Each event implements ShouldDispatchAfterCommit. The account purge calls these actions inside its own transaction, so a listener hears of a change only once the whole of it has committed, and never hears of one that rolled back. Outside a transaction an event is dispatched at once.
  • Once, and only for a change. An action that refuses fires nothing: a join the plan or ensureCanJoin() refuses, the owner being removed, a delete or trash the billing guard refuses, a restore after the window closed, a transfer to a user who is not a member. Neither does a call that changes nothing: removing someone who is not a member, restoring a team that is not trashed, transferring a team to the owner it already has.
  • Keys, not models. The payload is keys as strings, whatever the key type, and nothing else: no model, name or address, so a queued listener loads what it needs when it runs. TeamDeleted cannot load its members, because the team and its memberships are gone by then, so it carries memberIds, read before the members are detached.
  • A bound action owns its event. The events are dispatched by the default actions. An application that binds its own class over AddsTeamMembers, RemovesTeamMembers, DeletesTeams, TrashesTeams, TransfersTeamOwnership or AcceptsTeamInvitations without extending the default has to dispatch them itself. Extending the default and overriding one hook keeps them.

Two departures follow from what the actions do. Deleting a team detaches its members without firing TeamMemberRemoved for each: TeamDeleted and its memberIds are the record. Deleting an account detaches the user from the other teams they belonged to the same way, and fires no event for it.

Transferring Ownership#

TransferTeamOwnership makes the new owner the owner and leaves the outgoing owner on the team as an admin. A host whose teams have fewer roles overrides outgoingRole() and keeps the rest of the transfer, the event included:

php
use FlutterSdk\MagicStarter\Actions\TransferTeamOwnership;
use FlutterSdk\MagicStarter\Contracts\TransfersTeamOwnership;
use FlutterSdk\MagicStarter\Enums\Role;

class TransferHouseholdOwnership extends TransferTeamOwnership
{
    protected function outgoingRole(): Role
    {
        return Role::MEMBER;
    }
}

// AppServiceProvider::register()
$this->app->bind(TransfersTeamOwnership::class, TransferHouseholdOwnership::class);

Return anything but Role::OWNER: the new owner takes that role in the same transfer.


Authorization#

TeamPolicy#

TeamPolicy is automatically registered by the service provider when the teams feature is enabled. Consumers can override it:

php
// In your AuthServiceProvider
Gate::policy(Team::class, CustomTeamPolicy::class);

App providers boot after package providers, so the override takes precedence.

Policy Abilities Summary#

Ability Allowed For Used By
view Team members (owner + members) TeamController@show, TeamMemberController@index
update Owner only TeamController@update, TeamPhotoController
delete Owner only TeamController@destroy
restore Owner only TeamController@restore
manageMembers Owner or admin role TeamMemberController@update, TeamMemberController@destroy
manageInvitations Owner or admin role TeamInvitationController@index, store, destroy
switchTo Team members (owner + members) SwitchTeamRequest authorization

Models#

Team#

Class: FlutterSdk\MagicStarter\Models\Team

Property Type Description
id string Primary key (UUID or integer via ConditionallyUsesUuids)
user_id string Owner's user ID (foreign key)
name string Team name
personal_team bool Whether this is a personal (non-deletable) team
profile_photo_path string|null Stored photo path on disk
profile_photo_url string|null (read) Stored photo URL, or null when none is stored
created_at Carbon|null Timestamp
updated_at Carbon|null Timestamp
deleted_at Carbon|null Set on a trashed team; only with the restorable delete
restore_until Carbon|null End of a trashed team's restore window; only with the restorable delete

Relationships:

Method Type Description
owner() BelongsTo The user who owns the team
users() BelongsToMany Members via team_user pivot (with role, uses MagicStarter::membershipModel())
invitations() HasMany Pending TeamInvitation records

Fillable: user_id, name, personal_team, profile_photo_path

Casts: personal_team as boolean, restore_until as datetime

Appends: profile_photo_url


TeamUser (Pivot)#

Class: FlutterSdk\MagicStarter\Models\TeamUser

Extends Illuminate\Database\Eloquent\Relations\Pivot. Uses the team_user table.

Property Type Description
id string Primary key
team_id string Foreign key to teams
user_id string Foreign key to users
role string|null Member role (admin, editor, member)
created_at Carbon|null Timestamp
updated_at Carbon|null Timestamp

Uses ConditionallyUsesUuids for runtime UUID/integer PK switching.


TeamInvitation#

Class: FlutterSdk\MagicStarter\Models\TeamInvitation

Property Type Description
id string Primary key
team_id string Foreign key to teams
email string Invited email address
role string Role to assign upon acceptance
token string Unique acceptance token
expires_at Carbon|null Expiration timestamp (null = no expiry)
created_at Carbon|null Timestamp

Fillable: email, role, token, expires_at

Casts: expires_at as datetime

Relationships:

Method Type Description
team() BelongsTo The team this invitation is for

Methods:

Method Returns Description
isExpired() bool true if expires_at is set and in the past
scopeValid() Builder Scope to non-expired invitations (null or future date)

Roles#

Roles are defined in FlutterSdk\MagicStarter\Enums\Role:

Role Value Assignable Description
OWNER owner No Determined by team.user_id, not pivot
ADMIN admin Yes Can manage members and invitations
EDITOR editor Yes Standard elevated role
MEMBER member Yes Default member role

The owner role is never assigned via the pivot table -- it is resolved at runtime by comparing team.user_id with the user's ID. Only admin, editor, and member are valid values for invitation and member role updates.


HasTeams Trait#

Trait: FlutterSdk\MagicStarter\Traits\HasTeams

Applied to the User model to provide team relationship methods.

Method Returns Description
ownedTeams() HasMany Teams where the user is the owner (user_id)
teams() BelongsToMany Teams the user is a member of (via team_user pivot with role)
personalTeam() Model|null The user's personal team (personal_team = true)
currentTeam() BelongsTo The user's currently active team (current_team_id)
allTeams() Collection Merged owned + member teams, sorted by name
getCurrentTeamOrPersonal() Model|null Current team with personal team fallback
belongsToTeam(Model $team) bool Whether the user owns or is a member of the team
ownsTeam(Model $team) bool Whether the user owns the team (user_id match)
hasTeamRole(Model $team, string $role) bool Whether the user has the given role on the team (does not check ownership)
esc

Search index did not load.

No match for "".

Try a class like rounded-lg or a widget like WButton.