API Naming

API Naming Decision

Final owner decision, 9 November 2026. Applies locally to Moztopia Access.

One explicit vocabulary

$user->assignRole('editor');
$user->assignPermission('documents.edit', team: 'editorial');
$user->assignTeam('editorial');

$user->revokeRole('editor', team: 'editorial');
$user->revokePermission('documents.edit', team: 'editorial');
$user->revokeTeam('editorial');

These are the user mutation commands. Checks remain hasRole, hasPermission and hasTeam; teams() is the queryable relationship. There are no alternate mutation names, fluent builders or compatibility bridges. Explicit names make code easier to read, including for readers using English as an additional language. With AI-assisted code migration available, matching another package's command spellings does not justify expanding this public API.

An earlier proposal to retain grant/give/allow aliases was explicitly superseded by the owner before any package release. Those methods have been removed rather than deprecated. Existing evaluation code must use the explicit assign commands. No root-namespace trait shim is supplied either: import Moztopia\Access\Traits\HasAccess, now located at src/Traits/HasAccess.php under the mandated Laravel package trait-folder standard.

Mutation semantics

The receiver identifies the target user, never the acting user. The host must authorize management actors separately. Assigning a team adds membership only; it neither creates an unknown team nor grants permissions. Scoped role/permission assignments require membership.

revokeTeam() removes membership and permanently removes that membership's scoped assignments. It preserves the team, global grants and other-team grants. Repeating it for absent membership is safe; an unknown team fails clearly. Rejoining does not restore removed assignments. Team deletion remains the separate administrative deleteTeam() operation.

revokeRole and revokePermission affect only their explicit assignment scope. Revoking a direct permission does not deny access still inherited through a role.

Explicit team identity

$team = $access->createTeam('editorial', displayName: 'Editorial');
$user->assignTeam('editorial');
$user->assignTeam($team);

Names in examples are illustrative. Applications define their own unique stable lookup names. Display labels may change independently. Membership management, scoped assignments and checks accept an existing team model or its exact lookup name. Strings are not display labels, wildcards or overloaded UUIDs. Unknown named teams fail during mutation and fail closed during checks; no team is created implicitly.