PHPackages                             scafera/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. scafera/auth

ActiveSymfony-bundle[Authentication & Authorization](/categories/authentication)

scafera/auth
============

Authentication and access control for the Scafera framework

v1.0.1(1mo ago)06MITPHPPHP >=8.4

Since Apr 14Pushed 1mo agoCompare

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

READMEChangelog (2)Dependencies (3)Versions (3)Used By (0)

scafera/auth
============

[](#scaferaauth)

Authentication and access control for the Scafera framework. Provides session management, guards, login/logout, and password hashing — all behind Scafera-owned types.

Internally adopts `symfony/http-foundation` Session and `symfony/password-hasher`. Userland code never imports Symfony types — boundary enforcement blocks it at compile time.

> **Provides:** Authentication and access control for Scafera — `Authenticator` (login/logout), `Session` (state + flash), `Password` (hash / verify / `needsRehash`), `#[Protect]` attribute with `GuardInterface` guards, plus `CookieJar` for secure cookies. User-existence-based authentication per ADR-058.
>
> **Depends on:** A Scafera host project that implements `User` and `UserProvider` (how auth finds an identity). When exactly one `UserProvider` implementation exists, it is auto-aliased for injection.
>
> **Extension points:**
>
> - Contracts — `User`, `UserProvider`, `GuardInterface`
> - Attribute — `#[Protect(guard: ..., options: [...])]` on controllers
> - Built-in guards — `SessionGuard` and `RoleGuard`; implement `GuardInterface` for custom guards
> - Config — `scafera_auth.global` (guards applied to every request), `scafera_auth.exclude` (paths bypassing global guards)
>
> **Not responsible for:** User storage (app implements `UserProvider`) · password complexity / policy rules · two-factor auth or passkey flows · session storage backend (Symfony's responsibility) · direct use of `Symfony\Component\Security`, `HttpFoundation\Session`, `PasswordHasher`, `HttpFoundation\Cookie` in userland (blocked by `AuthBoundaryPass` and `AuthBoundaryValidator`).

This is a **capability package**. It adds optional authentication and access control to a Scafera project. It does not define folder structure or architectural rules — those belong to architecture packages.

What it provides
----------------

[](#what-it-provides)

- `Session` — session state management with flash messages
- `CookieJar` — secure cookie handling (auto-applied via response listener)
- `Authenticator` — login, logout, user resolution
- `Password` — hash, verify, needsRehash
- `GuardInterface` + `#[Protect]` — route protection
- `SessionGuard` and `RoleGuard` — built-in guards
- `User` + `UserProvider` — user identity contracts

Design decisions
----------------

[](#design-decisions)

- **User existence is the source of truth** — `isAuthenticated()` verifies the user still exists in the provider, not just that a session key is present. One cached DB lookup per request (ADR-058).
- **Session fixation prevention** — session ID is regenerated on both login and logout.
- **Explicit guard execution** — guards are declared via `#[Protect]` attributes on controllers, not via implicit firewall rules. Options are passed directly to `check()` — no magic attributes.

Installation
------------

[](#installation)

```
composer require scafera/auth
```

Requirements
------------

[](#requirements)

- PHP >= 8.4
- scafera/kernel

Session
-------

[](#session)

```
use Scafera\Auth\Session;

$session->set('key', 'value');
$session->get('key');              // 'value'
$session->has('key');              // true
$session->remove('key');
$session->flash('notice', 'Saved!');
$session->getFlash('notice');      // ['Saved!']
```

Safe in CLI context — returns defaults when no request exists.

Authentication
--------------

[](#authentication)

```
use Scafera\Auth\Authenticator;
use Scafera\Auth\Password;

// Login
$user = $userProvider->findByIdentifier($email);
if ($user && $password->verify($user->getPassword(), $plainPassword)) {
    $authenticator->login($user);
}

// Check
$authenticator->isAuthenticated();  // true
$authenticator->getUser();          // User instance

// Logout
$authenticator->logout();

// Rehash check (on login)
if ($password->needsRehash($user->getPassword())) {
    // update stored hash
}
```

User contracts
--------------

[](#user-contracts)

Implement these in your application:

```
use Scafera\Auth\User;
use Scafera\Auth\UserProvider;

final class AppUser implements User
{
    public function getIdentifier(): string;
    public function getRoles(): array;
    public function getPassword(): string;
}

final class AppUserProvider implements UserProvider
{
    public function findByIdentifier(string $identifier): ?User;
}
```

When exactly one `UserProvider` implementation exists, it is auto-aliased for injection.

Route protection
----------------

[](#route-protection)

```
use Scafera\Auth\Protect;
use Scafera\Auth\SessionGuard;
use Scafera\Auth\RoleGuard;

#[Protect(guard: SessionGuard::class)]
final class EditProfile
{
    // Only authenticated users reach this controller
}

#[Protect(guard: RoleGuard::class, options: ['role' => 'ADMIN'])]
final class AdminDashboard
{
    // Only users with ADMIN role
}
```

Guards run in declaration order. Return `null` to allow, or a `ResponseInterface` to deny. Options from `#[Protect]` are passed directly to `check()` — no magic attributes.

Global guards
-------------

[](#global-guards)

```
# config/config.yaml
scafera_auth:
    global:
        - App\Guard\MaintenanceGuard
    exclude:
        - /health
        - /login
```

Global guards run before route-specific guards. Excluded paths are matched exactly or as prefixes with `/`.

Boundary enforcement
--------------------

[](#boundary-enforcement)

BlockedUse instead`Symfony\Component\HttpFoundation\Session\*``Scafera\Auth\Session``Symfony\Component\HttpFoundation\Cookie``Scafera\Auth\CookieJar``Symfony\Component\Security\*``Scafera\Auth\Authenticator`, `GuardInterface``Symfony\Component\PasswordHasher\*``Scafera\Auth\Password`Enforced via compiler pass (build time) and validator (`scafera validate`). Detects `use`, `new`, and `extends` patterns.

License
-------

[](#license)

MIT

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance89

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity52

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

Every ~1 days

Total

2

Last Release

54d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/e9233f415f42755f68dc3006e2853b76c34de54b04c9535202b70aa147790e6a?d=identicon)[samaphp](/maintainers/samaphp)

---

Top Contributors

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

---

Tags

phpauthsessionscafera

###  Code Quality

TestsPHPUnit

### Embed Badge

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

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

###  Alternatives

[symfony/security-bundle

Provides a tight integration of the Security component into the Symfony full-stack framework

2.5k181.3M2.2k](/packages/symfony-security-bundle)[hyperf-ext/auth

The Hyperf Auth package.

2378.7k3](/packages/hyperf-ext-auth)[kinde-oss/kinde-auth-php

Kinde PHP SDK for authentication

2280.2k3](/packages/kinde-oss-kinde-auth-php)

PHPackages © 2026

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