PHPackages                             componenta/auth - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. componenta/auth

ActiveLibrary[Authentication & Authorization](/categories/authentication)

componenta/auth
===============

Authentication contracts and helpers for Componenta applications

v1.0.0(1mo ago)06MITPHPPHP ^8.4

Since Jun 21Pushed 1mo agoCompare

[ Source](https://github.com/componenta/auth)[ Packagist](https://packagist.org/packages/componenta/auth)[ RSS](/packages/componenta-auth/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (14)Versions (2)Used By (0)

Componenta Auth
===============

[](#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
------------

[](#installation)

```
composer require componenta/auth
```

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
------------

[](#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
----------------

[](#related-packages)

PackageWhy it matters here`componenta/session`Stores browser session state and session ids for session authentication.`componenta/app-http`Wires authentication middleware into HTTP applications that use PSR-7 requests and PSR-15 middleware.`componenta/event`Handles login, denial, logout, session regeneration, and session termination events.`componenta/policy`Uses the authenticated identity as the actor for authorization.`componenta/di`Builds strategies, token managers, middleware, and listeners from the container.Core Flow
---------

[](#core-flow)

```
use Componenta\Auth\Authenticator;
use Componenta\Auth\Context;
use Componenta\Auth\DeniedReasonInterface;
use Componenta\Identity\IdentityInterface;

$authenticator = new Authenticator(
    $passwordStrategy,
    $jwtStrategy,
    $sessionStrategy,
);

$result = $authenticator->attempt($payload, new Context());

if ($result->subject instanceof IdentityInterface) {
    $identity = $result->subject;
}

if ($result->subject instanceof DeniedReasonInterface) {
    $reason = $result->subject;
}
```

`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:

PropertyMeaning`$subject`Either the authenticated `IdentityInterface` or a `DeniedReasonInterface`.`$transportPayload`Optional object that must be persisted to the response transport, for example a rotated session or remember-me cookie payload.There is no separate boolean success flag. Consumers decide success by checking whether `$result->subject` is an `IdentityInterface`.

Strategy Contract
-----------------

[](#strategy-contract)

```
use Componenta\Auth\AuthenticationResult;
use Componenta\Auth\AuthenticationStrategyInterface;
use Componenta\Auth\ContextInterface;

final readonly class ApiKeyStrategy implements AuthenticationStrategyInterface
{
    public function supports(object $payload, ContextInterface $context): bool
    {
        return $payload instanceof ApiKeyPayload;
    }

    public function attempt(object $payload, ContextInterface $context): AuthenticationResult
    {
        // Return AuthenticationResult with IdentityInterface on success,
        // or DeniedReasonInterface on failure.
    }
}
```

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
----------------------------

[](#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
--------

[](#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:

```
$result = $sessionStrategy->attempt($sessionPayload, $context);
```

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

Tokens
------

[](#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
------

[](#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
---------------

[](#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:

Attribute keyValue`Componenta\Identity\IdentityInterface::class`Present when authentication succeeds.`Componenta\Auth\DeniedReasonInterface::class`Present when a supporting strategy denies the request.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
---------------

[](#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`:

KeyPurpose`ConfigKey::AUTH`Root authentication configuration.`ConfigKey::STRATEGIES`Ordered authentication strategies.`ConfigKey::SESSION`Session authentication and session manager options.`ConfigKey::REMEMBER_ME`Remember-me token options.`ConfigKey::JWT`JWT access/refresh token options.`ConfigKey::MAGIC_LINK`Magic-link request and verification options.`ConfigKey::PASSWORD_RESET`Password reset token options.`ConfigKey::DENIED`HTTP response factory for denied authentication.`ConfigKey::LISTENERS`Authentication event listeners.Failure Model
-------------

[](#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.

###  Health Score

41

—

FairBetter than 87% of packages

Maintenance92

Actively maintained with recent releases

Popularity6

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

39d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/20490712?v=4)[Andrey Shelamkoff](/maintainers/Shelamkoff)[@Shelamkoff](https://github.com/Shelamkoff)

---

Top Contributors

[![Shelamkoff](https://avatars.githubusercontent.com/u/20490712?v=4)](https://github.com/Shelamkoff "Shelamkoff (2 commits)")

### Embed Badge

![Health badge](/badges/componenta-auth/health.svg)

```
[![Health](https://phpackages.com/badges/componenta-auth/health.svg)](https://phpackages.com/packages/componenta-auth)
```

###  Alternatives

[symfony/symfony

The Symfony PHP framework

31.4k87.2M2.2k](/packages/symfony-symfony)[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k17](/packages/tempest-framework)[cakephp/cakephp

The CakePHP framework

8.8k19.5M1.8k](/packages/cakephp-cakephp)[ecotone/ecotone

Enterprise architecture layer for Laravel and Symfony — CQRS, Event Sourcing, Durable Workflows (Sagas, Orchestrators), Projections, and Outbox messaging via PHP attributes.

564576.7k54](/packages/ecotone-ecotone)[typo3/cms

TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL.

1.2k1.9M122](/packages/typo3-cms)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

85036.3k](/packages/flow-php-flow)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)