README

The Identity library provides an abstraction for representing and working with user identities in a PHP application. It is designed to be minimal, framework-agnostic, and flexible enough to integrate with different authentication or authorization systems.

Overview

At its core, the library defines the Identity interface, which describes the basic shape of an identity object:

• ID — A unique numeric identifier for the identity.
• Name — A simple, technical name without whitespace (e.g., admin, guest).
• Label — A more human-readable label for display purposes.
• Roles — One or more assigned roles that can be checked when making authorization decisions.

Special identities are predefined:

• ID_PRIVILEGED → Represents a super user with all privileges.
• ID_TRANSIENT → Represents a guest/anonymous user with no privileges.

Features

• Clear contract for what an identity must provide (Identity interface).
• Built-in handling for privileged and transient users.
• Role management via hasRole(), getRoleList().
• Separation of concerns: identities only describe users, leaving persistence and authentication to higher layers.

GenericIdentity

The library includes a ready-to-use implementation: GenericIdentity.

GenericIdentity is an in-memory, container-style implementation of the Identity interface. It allows developers to:

• Manually assign IDs, names, labels, and roles.
• Reset identities back to a transient (guest) state.
• Programmatically manage roles without any database dependency.

This makes it particularly useful for:

• Unit testing and mocking.
• Lightweight applications without complex identity backends.
• Prototyping or temporary/system identities.

Example

use gabbro\identity\GenericIdentity;
use gabbro\identity\Identity;

// Create a privileged identity
$admin = new GenericIdentity(Identity::ID_PRIVILEGED);

var_dump($admin->hasRole("anything")); // true

// Create a normal user identity
$user = new GenericIdentity(42, "jdoe", "John Doe");
$user->addRoles("editor", "contributor");

var_dump($user->getId());        // 42
var_dump($user->getName());      // "jdoe"
var_dump($user->getLabel());     // "John Doe"
var_dump($user->hasRole("editor")); // true
var_dump($user->hasRole("admin"));  // false