Home

InitPHP Auth — Wiki

Welcome to the official documentation for initphp/auth — a small PHP 8 authentication & authorization library with pluggable storage adapters (session, signed cookie, custom) and a tiny case-insensitive permission set.

The package ships these public types:

Type	Purpose
Segment	Facade in front of a single adapter. Pick the adapter via factory methods.
AdapterInterface	Storage contract — depend on this in your services.
AbstractAdapter	Base class with a default collective(). Most custom adapters extend this.
SessionAdapter	$_SESSION-backed storage.
CookieAdapter	Signed-cookie storage (JSON + HMAC-SHA256).
NullAdapter	Null Object — accepts every operation, stores nothing.
CookieWriterInterface	Abstraction over setcookie() so the cookie adapter is testable.
Permission	Case-insensitive named permission set.

composer require initphp/auth

useInitPHP\Auth\Permission;
useInitPHP\Auth\Segment;
session_start();
$auth = Segment::session('auth');
$auth->set('user_id', 42)->set('role', 'editor');
$perm = newPermission([$auth->get('role')]);
if ($perm->is('editor')) {
// do editor things
}

Start here

• New to the package? Read Installation, then Quick Start.
• Building a permission system? Read Permissions.
• Choosing an adapter? See the adapter comparison in Quick Start → Picking an adapter and the per-adapter pages: Session · Cookie · Null · Custom.
• Auditing cookie security? Read Security and Cookie Adapter → Wire format.
• Writing tests against the auth layer? Read Testing.
• Upgrading from v1? Read the Migration Guide.
• Looking for a specific method? The full API Reference lists every class member.

At a glance — adapter feature matrix

Capability	SessionAdapter	CookieAdapter	NullAdapter	Custom
Per-request lifetime	✅ (until session ends)	✅ (until expiry)	n/a	✅
Survives PHP restart	⚠️ (if session save handler persists)	✅	n/a	depends
Stateless server	❌	✅	✅	depends
Tamper-proof	✅ (server-side)	✅ (HMAC-SHA256)	n/a	depends
Capacity	bounded by $_SESSION	bounded by cookie size (~4 KB)	unlimited (no-op)	depends
Testable without headers	n/a	✅ (CookieWriterInterface)	✅	depends
Atomic bulk write (collective())	✅ (one $_SESSION write)	✅ (one Set-Cookie)	n/a	implements default

Package metadata

• License: MIT
• Minimum PHP: 8.0 (tested through 8.4)
• Runtime dependencies: initphp/parameterbag^2.0
• PHP extensions: ext-json, ext-hash (bundled with default PHP builds)
• Packagist: initphp/auth
• Source: github.com/InitPHP/Auth
• Issues: github.com/InitPHP/Auth/issues
• Discussions: github.com/orgs/InitPHP/discussions
• Security: SECURITY.md

If something in this wiki is unclear, ambiguous, or wrong, please open an issue — documentation fixes are reviewed eagerly.