Access Control¶

ZubZet now includes significantly enhanced access control and permission capabilities. The system is built to provide a flexible and extensible authorization workflow, improved developer ergonomics, and full support for user-based and role-based permissions.

At its core, the access control system introduces two primary domain objects: User and Role. Permissions can be assigned directly to users or indirectly through roles. All permission checks automatically resolve the combined permission set.

User Object¶

The User object represents an application user and exposes a comprehensive API for retrieval, lifecycle management, and permission handling.

User Retrieval¶

All retrieval methods are public static and return fully hydrated User objects.

Returns all users assigned to the given role.
```
User::byRole(Role $role): array
```
Returns a single user by email address or null if no user exists.
```
User::byEmail(string $email): ?User
```
Returns all users that were not verified up to the given date.
```
User::byNotVerified(DateTime $since): array
```
Returns all users that have all of the specified permissions. This includes user-based permissions and role-based permissions.
```
User::byAccessToAll(string ...$permissions): array
```
Returns all users that have at least one of the specified permissions. This includes user-based permissions and role-based permissions.
```
User::byAccessToAnyOf(string ...$permissions): array
```
Returns all users.
```
User::all(): array
```
Returns a user by its ID or null if not found.
```
User::byId(int|string $id): ?User
```
Returns all users matching the given IDs.
```
User::byIds(int ...$ids): array
```

Loading a User from Database Data¶

If a user instance needs to be created from an existing database row, the object can be hydrated manually.

Loads raw database data into a user object.

$user = (new User())->loadObject(array $data);

Creating a User¶

Users can be created through the static add method.

Creates a new user.

User::add(?string $email, string $password, ?DateTime $verified = null);

If no verification date is provided, the user is created as unverified.

Updating User Data¶

User attributes can be updated directly on the instance.

Updates the user’s email address.
```
$user->updateEmail(?string $email);
```

Updates the user’s password.

$user->updatePassword(string $password);

Clears all active login sessions for the user.
```
$user->clearSessions();
```

Removing a User¶

Removing a user performs a soft delete.

Soft deletes the user (active = 0).
```
$user->remove();
```

Verification Handling¶

Verification status is time-aware and can be set or queried at arbitrary points in time.

Marks the user as verified. Defaults to NOW if no date is provided.
```
$user->verify(?DateTime $date = null);
```
Checks whether the user was verified at a specific time.
```
$user->isVerified(string $at = "NOW"): bool
```

Role Assignment¶

Users can have multiple roles assigned or removed dynamically.

Adds one or more roles to the user.
```
$user->rolesAdd(Role ...$roles);
```
Removes one or more roles from the user.
```
$user->rolesRemove(Role ...$roles);
```

User-Based Permissions¶

Permissions can be assigned directly to users in addition to role-based permissions.

Adds user-based permissions.

$user->permissionsAdd(string ...$permissionNames);

Removes user-based permissions.

$user->permissionsRemove(string ...$permissionNames);

Permission Checks¶

Permission checks always resolve the complete permission set.

Checks whether the user has all specified permissions.

$user->hasAccessAll(string ...$permissionNames): bool

Checks whether the user has at least one of the specified permissions.
```
$user->hasAccessAnyOf(string ...$permissionNames): bool
```

Permission Retrieval and Refresh¶

Returns only user-based permissions.
```
$user->getUserPermissions(): array
```
Returns all effective permissions (user-based + role-based).
```
$user->getPermissions(): array
```
Reloads user-based permissions.
```
$user->refreshPermissions();
```
Reloads all permissions including roles.
```
$user->refreshAllPermissions();
```

User Data & Utility Methods¶

Reloads the user data from the database.
```
$user->refresh();
```
Returns the user’s email address.
```
$user->email(): ?string
```
Returns the verification timestamp.
```
$user->verified(): ?string
```
Returns the user ID.
```
$user->id(): int|string|null
```
Returns all roles assigned to the user.
```
$user->getRoles(): array
```
Validates that the instance exists and is not null.
```
$user->checkInstance(): bool
```

Role Object¶

The Role object represents a named collection of permissions that can be assigned to users.

Role Retrieval¶

Returns all roles assigned to a user.
```
Role::byUser(User $user): array
```
Returns a role by its name.
```
Role::byName(string $name): ?Role
```

Returns all roles that have all specified permissions.

Role::byAccessToAll(string ...$permissions): array

Returns all roles that have at least one of the specified permissions.
```
Role::byAccessToAnyOf(string ...$permissions): array
```
Returns all roles.
```
Role::all(): array
```
Returns a role by ID.
```
Role::byId(int|string $id): ?Role
```
Returns all roles matching the given IDs.
```
Role::byIds(int ...$ids): array
```

Role Creation and Loading¶

Creates a new role.
```
Role::add(string $roleName);
```

Loads a role from database data.

$role = (new Role())->loadObject(array $data);

Updating and Removing Roles¶

Updates the role name.
```
$role->update(string $newName);
```
Soft deletes the role.
```
$role->remove();
```

Role Data Access¶

Returns the role name.
```
$role->name(): string
```
Returns all users assigned to the role.
```
$role->getUsers(): array
```
Reloads the role’s users.
```
$role->refreshUsers();
```

Role Permissions¶

Returns all permissions assigned to the role.
```
$role->getPermissions(): array
```
Reloads role permissions.
```
$role->refreshPermissions();
```

Adds permissions to the role.

$role->permissionsAdd(string ...$permissionNames);

Removes permissions from the role.

$role->permissionsRemove(string ...$permissionNames);

Role Permission Checks¶

Checks whether the role has all specified permissions.

$role->hasAccessAll(string ...$permissionNames): bool

Checks whether the role has at least one of the specified permissions.
```
$role->hasAccessAnyOf(string ...$permissionNames): bool
```

Refreshing Role Data¶

Reloads the role data from the database.
```
$role->refresh();
```

Session Object¶

The Session object represents a login session (stored in z_logintoken) and provides methods for creation, retrieval, lifetime management, and invalidation.

Session Retrieval¶

Returns a session by its token string, or null if not found.
```
Session::byToken(string $token): ?Session
```
Returns all active sessions for a given user.
```
Session::byUser(User $user): array
```

Returns a session by its ID.

Session::byId(int|string $id): ?Session

Returns all sessions matching the given IDs.
```
Session::byIds(int ...$ids): array
```
Returns all sessions.
```
Session::all(): array
```

Creating a Session¶

Creates a new login session for a user. An optional $userExec can be passed to create an impersonation session where $user is the target user and $userExec is the acting. If omitted, both are set to $user.
```
Session::add(User $user, ?User $userExec = null): Session
```

Lifetime Management¶

Extends the session's lifetime by the given number of seconds on top of the base timeout and any existing extension.
```
$session->extend(int $seconds): void
```
Sets the total extension time in seconds, replacing any previously set extension.
```
$session->setExtensionTime(int $seconds): void
```

Invalidation¶

Immediately invalidates the session, preventing further use.
```
$session->invalidate(): void
```

Expiry Check¶

Returns true if the session has expired. The expiry is calculated from created plus the configured loginTimeoutSeconds (defaults to 7 days) plus any extended_seconds.
```
$session->isExpired(): bool
```

Session Data¶

Returns the session token string.
```
$session->token(): string
```
Returns the ID of the user who owns the session.
```
$session->userId(): int|string
```
Returns the ID of the user being executed as (relevant for impersonation sessions).
```
$session->userIdExec(): int|string
```
Returns the number of seconds the session has been extended by, or null if not extended.
```
$session->extendedSeconds(): ?int
```
Returns the creation timestamp of the session.
```
$session->created(): string
```

Refreshing Session Data¶

Reloads the session data from the database.
```
$session->refresh(): void
```