Download the PHP package sirix/mezzio-rbac without Composer

Mezzio RBAC

RBAC authorization package for Mezzio with PSR-15 middleware and optional PHP attribute integration.

Installation

Package is auto-registered via extra.laminas.config-provider.

Core Concepts

Actor

Current subject is represented by ActorInterface.

Guest fallback is provided by Sirix\Mezzio\Rbac\Actor\GuestActor.

Authorization paths

The package has two authorization paths:

GuardInterface remains request-independent. It uses ActorProviderInterface and is useful from services, CLI commands, or application-managed contexts.

AuthorizeMiddleware uses RequestGuardInterface so it can authorize against the actor stored on the current PSR-7 request.

Guard

Main non-HTTP authorization entrypoint:

authorize() throws Sirix\Mezzio\Rbac\Exception\AuthorizationException with HTTP status 403.

Request Guard

HTTP-aware authorization entrypoint:

For route-level protection, prefer AuthorizeMiddleware or #[Can].

Permissions

Permissions use dot-notation and wildcard matching:

• posts.read
• posts.update
• admin.users.delete
• posts.* (greedy match)
• admin.*.delete (exact segment count)

Example:

Resolution rules:

• exact match beats wildcard;
• more specific wildcard beats broader wildcard;
• latest association wins when specificity is equal;
• another actor role may still grant access if one role forbids it.

Conflict Resolution: Allow wins over Deny

The package follows an "Allow wins over Deny" policy. If an actor has multiple roles, access is granted if at least one role allows the permission.

Example: if a user has both user allowed posts.read and banned forbidden posts.read, the user still has access because the user role grants it.

Wildcard Matching

Permissions use dot-notation and support greedy terminal wildcard matching:

• posts.* matches posts.read, posts.update, and nested resources like posts.read.history.
• admin.* grants access to all sub-resources of any depth.
• Non-terminal wildcards, for example admin.*.delete, still require exact segment positioning.

Rules

Built-in rules:

• Sirix\Mezzio\Rbac\Rule\AllowRule
• Sirix\Mezzio\Rbac\Rule\ForbidRule

Custom rules implement Sirix\Mezzio\Rbac\Contract\RuleInterface:

Then associate it with a permission:

HTTP Integration

Actor resolution for HTTP requests

AuthorizeMiddleware resolves the actor from the current request through RequestActorProviderInterface.

The default provider reads this request attribute:

This default matches sirix/mezzio-authentication, which stores the authenticated actor in sirix.authentication.actor.

If the request attribute contains an RBAC ActorInterface, it is used directly. If it contains an authentication-like object with getRoles(), it is adapted to an RBAC actor. Missing or invalid actor values fall back to GuestActor.

ContainerActorProvider is still available for non-request usage through GuardInterface, but it should not be used to resolve the current HTTP user.

Metadata resolution

AuthorizeMiddleware resolves permission metadata in this order:

1. request attribute sirix.rbac.permission;
2. matched route option sirix.rbac.permission;
3. if missing or empty, pass through without authorization.

Context follows the same order:

1. request attribute sirix.rbac.context;
2. matched route option sirix.rbac.context;
3. empty array.

Context values map request attributes into rule context:

With standard Mezzio routing

Register AuthorizeMiddleware in your route pipeline and set permission/context as route options:

You can also set request attributes before AuthorizeMiddleware runs. Request attributes take precedence over route options.

With sirix/mezzio-routing-attributes

When used with sirix/mezzio-routing-attributes:^1.0, #[Can] implements RouteAttributeModifierInterface. It injects AuthorizeMiddleware into the route pipeline and stores permission/context in route options.

No manual middleware registration is needed for routes discovered by sirix/mezzio-routing-attributes.

Integration with sirix/mezzio-authentication

sirix/mezzio-authentication writes the current actor to request attribute sirix.authentication.actor. RBAC uses that attribute by default, so the usual route pipeline is:

With attributes:

Expected behavior:

• anonymous user is stopped by authentication;
• authenticated non-admin user receives 403;
• authenticated admin user receives 200.

Manual authorization from services

For services without a request, use GuardInterface:

Storage Boundary

The package depends on contracts, not on concrete persistence.

Public storage contract:

• Sirix\Mezzio\Rbac\Contract\PermissionStoreInterface

Read-only lookup contract used by authorization internals:

• Sirix\Mezzio\Rbac\Contract\PermissionLookupInterface

Default implementation:

• Sirix\Mezzio\Rbac\InMemoryPermissionStore

Later adapters can replace storage without changing the guard API.

Extensibility

Custom non-request actor provider

Use ActorProviderInterface for non-request authorization through GuardInterface:

Custom request actor provider

Use RequestActorProviderInterface for HTTP authorization through RequestGuardInterface / AuthorizeMiddleware:

Register it in your dependencies:

Custom Permission Store

Implement PermissionStoreInterface to load permissions from a database, cache, or another source:

Custom Rules

As shown in the Rules section, implement RuleInterface to add dynamic logic to permissions. Rules are resolved through RuleResolver, which can use the PSR-11 container or instantiate rule classes directly.

Main Components

• GuardInterface / Guard
• RequestGuardInterface / RequestGuard
• ActorProviderInterface
• RequestActorProviderInterface
• RequestAttributeActorProvider
• Permissions
• PermissionLookupInterface
• PermissionMatcher
• RuleResolver
• InMemoryPermissionStore
• AuthorizeMiddleware
• RbacAttribute
• #[Can(...)]