Download the PHP package tetranyble/kinship without Composer

Kinship

Kinship is a guard-aware role and permission package for Laravel 9–13 on PHP 8.2 or newer. Workspace authorization is optional: ordinary applications only add the user concern, while workspace applications can opt in with a small model contract, configuration mapping, or a custom resolver.

Design guarantees

• Workspace behavior is off unless a subject contract, complete mapping, or explicit configuration enables it.
• Every authorization operation is scoped by an immutable guard/workspace context.
• Permission and acting-role caches are isolated by that context.
• A workspace-aware user without a resolved workspace fails closed.
• The roles schema is stable in both application modes and supports integer, UUID, ULID, and string workspace identifiers.
• Role and permission soft deletion is enforced by the models.
• Host applications own their user and workspace models.

For deeper treatment, see:

• Authorization
• Permission caching and grant sources
• Support/admin user impersonation
• Workspace integration
• Configuration and schema
• Release process

Installation

Install the package from Packagist:

For local path-repository development before the first tagged release:

Laravel discovers KinshipServiceProvider automatically. Publish configuration or migrations when the application must own them:

Set kinship.migrations.load to false after publishing migrations so there is one migration owner.

Opt-in permission catalog

Kinship never seeds authorization data during installation, migration, or application boot. The catalog is disabled by default, and application-model discovery has a separate disabled-by-default switch. To use the supplied starter matrix, publish the configuration and explicitly enable it:

Preview and seed a non-workspace application:

The default catalog contains user, role, and permission resources with seven abilities and four starter roles:

The resource shorthand is optional. To own the complete permission vocabulary, set resources to an empty array and list arbitrary names. Names are opaque to Kinship, so dot, colon, or domain-specific conventions all work:

Applications migrating from a model-scanning permission system can opt into the compatibility adapter. It scans only concrete Eloquent models and only while the explicit seed command runs:

Discovered, configured-resource, and explicit permissions are merged, so an old application can migrate gradually.

In a workspace application the scope must be deliberate:

The command is idempotent and additive by default. --sync makes the configured matrix authoritative for the configured roles, while leaving unrelated roles and permission definitions untouched. See Configuration and schema for custom catalog classes and all command options.

Ordinary application

Add the concern to the authenticatable user model:

No workspace interface or relationship is required. Roles created without a workspace value are stored in Kinship's internal global scope and are unique by name, guard, and that scope.

Workspace application: model-contract path

The user model opts in by implementing WorkspaceSubject. Only the identifier is required, following the same integration style as contracts such as JWT subject models.

Any host Eloquent model can mark itself as a workspace:

Relationships are conveniences, not domain requirements. For the common belongs-to design, configure the model and keys, then use the supplied traits:

The traits provide kinshipWorkspace(), kinshipUsers(), and kinshipRoles() without forcing those methods into the identity contracts.

Configuration-only workspace mapping

Applications that cannot modify their user model can provide the complete mapping shown above. Kinship reads the configured foreign key first and falls back to the configured relationship. A partial mapping throws during startup/use instead of silently weakening authorization.

Custom workspace resolution

Domain-, request-, session-, or middleware-selected workspaces use the Strategy extension point:

Returning null while workspace mode is active denies all workspace roles. It never falls back to global roles.

Role and permission API

roles() is guard/workspace scoped. allRoles() is the explicitly named unscoped persistence relationship and should not be used for authorization decisions.

Permissions are global definitions scoped by guard. Direct user permissions therefore apply across that user's workspaces for the same guard; use role permissions when the grant must vary per workspace.

Permission checks resolve direct and role grants through one SQL UNION, then cache the flattened names through Laravel's configured cache store. A warm check on a fresh user instance performs no authorization query. Applications can append a PermissionGrantSource for teams or any other domain-owned grant mechanism without adding team schema to Kinship. See Permission caching and grant sources.

Acting roles

This changes the authorization role context, not the authenticated user. The default replace mode suspends normal grants while a role is assumed. Applications can explicitly select merge mode to add the role to normal access. Unassigned acting roles are denied by default; enable them only for an authorized preview workflow.

User impersonation

User impersonation is a separate, disabled-by-default capability for authorized support workflows. It switches Laravel's authenticated identity to the target without unlocking or modifying that account:

The package provides Gate authorization, a required reason, stateful-guard and session isolation, expiration, actor restoration, audit events, and a dedicated middleware alias. Applications explicitly attach that middleware, and may add a new subclass for continuous MFA, lock-state, suspension, compliance, or route-specific conditions; existing middleware remains unchanged. Stateless authentication uses a separate middleware and the typed StatelessImpersonationTokenBroker adapter contract; it is never attached to the web group. See Support/admin user impersonation.

Middleware

Put Laravel's auth:<guard> middleware before Kinship. With kinship.guard=null, Laravel selects the guard for the request: auth:api evaluates roles and permissions whose guard_name is api, while auth:web evaluates web. The middleware expression is auth:api; the guard value stored in Kinship and passed to kinship:seed --guard=api is only api.

Comma-separated Kinship arguments have any-of semantics. JSON denials return HTTP 403 with status and message fields.

Quality commands

The CI matrix covers Laravel 9/Testbench 7 through Laravel 13/Testbench 11. Laravel 9 is supported for compatibility, but it is upstream end-of-life; applications must assess unresolved framework advisories and plan an upgrade.

License

MIT