Download the PHP package sirix/mezzio-authentication without Composer

Mezzio Authentication

Token-based authentication package for Mezzio framework with optional attribute support.

Stability

The 1.x line treats the public contracts, middleware behavior, and request attribute names documented below as stable integration points.

Installation

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

Quick Start

1. Configuration

Add to config/autoload/authentication.global.php:

2. Session Setup (for SessionTokenStorage)

Register Mezzio\Session\SessionMiddleware in your pipeline before authentication middleware.

Also configure a session persistence adapter for your application (for example cookie-based or cache-backed persistence), per mezzio/mezzio-session documentation.

If mezzio/mezzio-session is not installed, SessionTokenStorage is not wired and the package uses NullTokenStorage as fallback.

If a token id is provided by transport but current storage backend is unavailable for that request (for example missing session in request), authentication middleware treats request as guest instead of failing with a storage runtime exception.

3. Protect Routes

Manual middleware registration:

With sirix/mezzio-routing-attributes (optional):

Core Concepts

AuthManager

Main HTTP-facing entry point for authentication operations. Current request authentication state is read from the provided ServerRequestInterface; it is not stored in a mutable singleton service.

For HTTP handlers and middleware, prefer AuthManagerInterface::actor($request) or the documented request attributes. Do not resolve a "current user" singleton from the container for per-request authorization.

Token Storage

Two built-in storage backends:

• NullTokenStorage — tokens are generated but not persisted (testing/stateless).
• SessionTokenStorage — tokens stored in session via mezzio/mezzio-session.

When mezzio/mezzio-session is unavailable, only NullTokenStorage is active.

Custom storage implements TokenStorageInterface.

Token Transport

Extracts token ID from requests:

• BearerTokenTransport — Authorization: Bearer <token> header.
• CookieTokenTransport — cookie-based transport.

Custom transport implements TokenTransportInterface.

Actors

Actors represent the authenticated user:

• PayloadActorProvider — extracts roles from token payload.
• ContextActorProvider — resolves actor from authentication context.
• GuestActor — default guest actor with role guest.

SecurityActorProviderInterface is intended for non-request or application-managed security contexts. Its default ContextActorProvider reads from the injected AuthContextInterface service and is not automatically synchronized with the current HTTP request. It is not a replacement for AuthManagerInterface::actor($request) in HTTP code.

Middleware

Attributes

When sirix/mezzio-routing-attributes is installed, attributes auto-inject middleware. Without it, middleware must be registered manually.

Request Attributes

After AuthenticateMiddleware or OptionalAuthenticateMiddleware processes a request, these stable attributes are available:

Stable attribute names:

These attributes are the package's current-request state boundary and are safe for long-running workers because they live on the PSR-7 request instance.

RBAC Integration

sirix/mezzio-rbac can authorize the current request by reading the actor from:

The authentication package does not depend on RBAC. The integration contract is structural: the actor exposes getRoles(): array.

SessionTokenStorage reads session from request attributes in this order:

1. Mezzio\Session\SessionInterface::class
2. 'session'

When using session storage, Mezzio\Session\SessionMiddleware must run before authentication middleware.

For cookie transport in production, use secure: true over HTTPS, keep http_only: true, and choose a same_site policy appropriate for your application flow.

Extensibility

Custom Actor Provider

Register in your dependencies:

Custom Token Storage

Custom Transport

Exceptions

HTTP exceptions provide getStatusCode(), getHeaders(), and getPublicMessage() for integration with error handling middleware. Factory configuration errors are reported by sirix/container-resolver exceptions.

Design Notes

The package depends on contracts, not on concrete persistence. Built-in implementations cover common use cases, but everything is replaceable via PSR-11 service configuration.