Download the PHP package componenta/auth without Composer

Componenta Auth

Authentication contracts and HTTP-oriented authentication building blocks for Componenta applications.

Use this package when an application needs more than one authentication mechanism: password login, bearer/JWT tokens, session authentication, remember-me cookies, OTP, magic links, password reset, or auth lifecycle events. The package is strategy-based: each mechanism decides whether it supports a payload, attempts authentication, and returns either an authenticated identity or a denial reason.

Installation

The package declares Componenta\Auth\ConfigProvider in extra.componenta.config-providers. When componenta/composer-plugin is installed, the provider is added to the generated provider list automatically.

Requirements

• PHP 8.4+
• PSR-7 / PSR-15 for HTTP middleware and handlers
• Storage adapters for the strategies you enable: sessions, remember-me tokens, refresh tokens, OTP codes, or password-reset tokens

Related Packages

Core Flow

Authenticator iterates over registered strategies in order. Unsupported strategies are skipped. Supporting strategies are attempted until one returns an IdentityInterface. If every supporting strategy denies the payload, the last denial is returned. If no strategy supports the payload, NoStrategyFoundException is thrown.

AuthenticationResult has two public properties:

There is no separate boolean success flag. Consumers decide success by checking whether $result->subject is an IdentityInterface.

Strategy Contract

Strategies must be deterministic for a given payload and context. They should not throw for normal authentication failure; return a denial result instead.

Payloads And HTTP Extraction

HTTP strategies are separated from payload extraction. A payload extractor reads a PSR-7 request and produces a strategy-specific payload object:

• bearer token payloads for Authorization: Bearer ...
• password payloads for login forms or JSON bodies
• session payloads
• OTP payloads
• magic-link verification payloads

This separation keeps strategies testable and lets applications define their own request shape without changing authentication logic.

Sessions

Session support includes session contracts, session collection, session attributes, ID generation, device detection, and database-backed session management.

Use session authentication when the browser already has a session id and the application can resolve it to a user:

Session lifecycle events are available for login/logout, regeneration, and termination flows.

Tokens

The package includes token helpers for:

• JWT access tokens and refresh tokens
• OTP request/verify flows
• magic-link request/verify flows
• password reset tokens
• remember-me tokens

Token managers own persistence and invalidation. Token handlers own signing/parsing and denial reasons such as expired, invalid, already used, or compromised tokens.

Events

EventingAuthenticator decorates authentication attempts with events:

• AuthenticationAttempted
• AuthenticationSucceeded
• AuthenticationDenied
• LoggedOut
• SessionRegenerated
• SessionsTerminated
• AllSessionsTerminated

Listeners are resolved through EventListenerProviderInterface. Use events for audit logs, session cleanup, remember-me token rotation, notifications, and metrics.

HTTP Middleware

The HTTP layer provides:

• AuthenticationMiddleware: attempts authentication and attaches auth state to the request/context.
• RequireAuthenticationMiddleware: rejects unauthenticated requests.
• TouchSessionMiddleware: updates session activity.
• SessionGarbageCollectionMiddleware: triggers storage cleanup.

The package does not prescribe route layout. Applications decide which routes are public and which routes require authentication.

AuthenticationMiddleware writes the result to PSR-7 request attributes:

If a strategy returns $transportPayload, the middleware requires a PayloadStorageInterface; otherwise it throws a LogicException because it cannot persist cookies or other response-side transport data.

DI Registration

ConfigProvider registers factories, aliases, listeners, token handlers, session managers, middleware, and default configuration keys used by the Componenta application runtime. Only the strategies and adapters wired by the application are active.

The main configuration keys are defined by ConfigKey:

Failure Model

Normal authentication failure is represented by DeniedReasonInterface, not an exception. Exceptions are reserved for infrastructure or programming errors: unsupported payloads, invalid payload extraction, storage failures, invalid token configuration, or transport failures.