README

A small PHP authentication & authorization library with pluggable storage adapters (session, signed cookie, or custom) and a tiny case-insensitive permission set.

Features

• Pluggable storage — pick SessionAdapter, CookieAdapter, or roll your own by implementing AdapterInterface.
• Signed cookies — JSON payload sealed with constant-time HMAC-SHA256; tampered values are dropped before decoding ever runs.
• Strict cookie defaults — Secure, SameSite=Lax, HttpOnly, and refusal of the unsafe SameSite=None + Secure=false combination.
• Testable — inject a CookieWriterInterface to capture every setcookie() call in unit tests instead of touching response headers.
• Tiny permission set — Permission does case-insensitive membership checks and ships magic accessors ($perm->is_admin).
• Honest contracts — typed properties, return types, @throws on every implementation-defined exception, PHPStan level 8 clean.

Requirements

• PHP 8.0 or later (tested on 8.0 – 8.4)
• ext-json, ext-hash (both bundled with default PHP builds)
• initphp/parameterbag ^2.0

Installation

composer require initphp/auth

Quick start

Session-backed auth

use InitPHP\Auth\Segment;

session_start();

$auth = Segment::session('auth');
$auth->set('user_id', 42)->set('role', 'editor');

if ($auth->has('user_id')) {
    $user = loadUser($auth->get('user_id'));
}

$auth->destroy(); // unsets $_SESSION['auth']

Signed-cookie auth

use InitPHP\Auth\Segment;

$auth = Segment::cookie('auth', [
    // 32+ byte secret. Generate with bin2hex(random_bytes(32)) and
    // load it from configuration — never hard-code it in source.
    'salt'   => $_ENV['AUTH_COOKIE_SECRET'],
    'path'   => '/',
    'domain' => 'example.com',
]);

$auth->set('user_id', 42);
echo $auth->get('user_id'); // 42

$auth->destroy(); // emits a deletion cookie with matching path/domain

Permissions

use InitPHP\Auth\Permission;

// Comparison is case-insensitive: 'Editor', 'EDITOR', and 'editor'
// are the same permission. The constructor normalizes its input the
// same way push() and remove() do.
$perm = new Permission(['Editor', 'post_list', 'post_edit']);

if ($perm->is('editor')) {
    $perm->push('user');         // returns 1
    $perm->remove('post_edit');  // returns 1
}

$perm->is('admin', 'editor');    // true if any of the names is present
isset($perm->is_admin);          // magic accessor for templates

Public API

Segment

AdapterInterface

Permission

Magic accessors: $perm->is_admin (call), isset($perm->is_admin), unset($perm->is_admin).

CookieAdapter options

Cookie wire format

base64url(json_encode($data)) . "." . hash_hmac('sha256', $json, $salt)

The signature is verified with hash_equals() before the JSON is decoded, so a forged or modified cookie never reaches the parser.

Exceptions

Development

composer install
composer test         # PHPUnit
composer analyse      # PHPStan (level 8)
composer cs:check     # PHP-CS-Fixer dry-run
composer cs:fix       # PHP-CS-Fixer apply

CI runs the matrix across PHP 8.0, 8.1, 8.2, 8.3, and 8.4.

Documentation

• docs/getting-started.md — five-minute tour
• docs/permissions.md — Permission recipes
• docs/adapters/session.md — SessionAdapter
• docs/adapters/cookie.md — CookieAdapter, salt generation, SameSite/Secure guidance
• docs/adapters/custom.md — building your own adapter (with a safe PDO-backed example)
• docs/adapters/null.md — NullAdapter and when to use it
• docs/upgrading-from-v1.md — v1 → v2 migration notes

Upgrading from v1

v2 ships intentional behaviour changes — most notably a new cookie format (old cookies become unreadable and are rolled), case-folding moved into the Permission constructor, a stricter cookie default profile, NullAdapter::has() returning false instead of true, and a clean adapter interface that no longer enforces a constructor signature. See docs/upgrading-from-v1.md.

Contributing & Security

• Contributing guidelines
• Code of Conduct
• Security policy

Credits

• Muhammet ŞAFAK <info@muhammetsafak.com.tr>

License

Released under the MIT License.