Documentation

User extends AuthenticationEntity
in package
Uses Permission, RetrievalTrait, HandleTrait

Table of Contents

$dbExpression  : array<string|int, mixed>
$dbPermissionsObjectColumn  : string
$dbPermissionsTable  : string
$dbTable  : string
__construct()  : mixed
add()  : User|null
Create a new user This will insert the user into the database and return the created user object
all()  : array<string|int, static>
Get a list of all active objects of the calling class (user, role, session, organization, API key)
buildPermissionVariants()  : array<string|int, string>
Build permission variants for a given permission name
byAccessToAll()  : array<string|int, mixed>
byAccessToAnyOf()  : array<string|int, mixed>
byEmail()  : User|null
Get a user by their email address
byGroup()  : array<string|int, mixed>
byId()  : static|null
Get an object (user, role, session, organization or API key) by its id
byIdentifier()  : object|null
Get a permission object (user or role) by one of its identifiers
byIdentifiers()  : array<string|int, object>
Get a list of permission objects (user or role) by one of their identifiers
byIds()  : array<string|int, static>
Get a list of objects (user, role, session, organization or API key) by their ids Unknown or inactive ids are skipped, and calling it without ids throws a database exception
byNotVerified()  : array<string|int, User>
Get a list of users who were not verified as of the $since DateTime
byOrganization()  : array<string|int, mixed>
byRole()  : array<string|int, User>
Get a list of users by a specific role, including members of organizations holding it
byUuid()  : object|null
Get a permission object (user or role) by its uuid
byUuids()  : array<string|int, object>
Get a list of permission objects (user or role) by their uuids
checkLoginTries()  : bool
clearSessions()  : void
Clear all sessions of the user
confirmTwoFactor()  : bool
Finish an enrollment. Turning two factor on takes a code, which is what proves the secret reached the authenticator and was not lost in the page.
disableTwoFactor()  : void
Drop two factor and the secret behind it
email()  : string|null
Get the user's email from the cache
getGroups()  : array<string|int, Group>
Get the user's groups
getPermissions()  : array<string|int, mixed>
Get the user's permissions including those inherited from roles
getRoles()  : array<string|int, Role>
Get the user's roles
getUserPermissions()  : array<string|int, mixed>
Get the user's permissions
groupsAdd()  : void
Add Groups to the user This will add the groups automatically into the database and clear all cached fields, so getters throw until refresh()
groupsRemove()  : void
Remove groups from the user This will remove the groups automatically from the database and clear all cached fields, so getters throw until refresh()
hasAccessAll()  : bool
Check if the permission object (user or role) has all of the given permissions, wildcards count ("*.*" or "edit.*" cover "edit.article") and a user's permissions include those inherited from its roles
hasAccessAnyOf()  : bool
Check if the permission object (user or role) has one of the permissions, wildcards included ("*.*" or "edit.*" cover "edit.article"); a user's role-inherited permissions count too
hasTwoFactor()  : bool
Whether two factor is active, which only a confirmed enrollment makes it.
isMemberOf()  : bool
isVerified()  : bool
Check if a User is verified
loadObject()  : void
Re-/Loads the user object
organization()  : Organization|null
permissionsAdd()  : void
Add permissions to an permission object (user or role)
permissionsRemove()  : void
Remove permissions from the permission object (user or role)
recordLoginTry()  : void
refresh()  : void
Refresh the current permission object (user, role, session, organization or API key) by clearing all its fields and setting them new
refreshAllPermissions()  : void
Reload the user's direct and role-inherited permissions into the cache
refreshPermissions()  : void
Reload the user's directly assigned permissions (not role-inherited ones) into the cache
remove()  : void
Deactivate this user The instance is detached afterwards, so every later call on it throws InvalidArgumentException
rolesAdd()  : void
Add roles to the user and clear all cached fields, so getters throw until refresh() This will add the roles automatically into the database
rolesRemove()  : void
Remove roles from the user and clear all cached fields, so getters throw until refresh() This will remove the roles automatically from the database
startTwoFactor()  : Totp
Begin an enrollment by storing a fresh secret that does not count yet.
twoFactorConfirmedAt()  : string|null
When the user confirmed their authenticator
updateEmail()  : void
Update the email address of the user This will update the email in the database and clear all cached fields, so getters throw until refresh()
updateOrganization()  : void
updatePassword()  : void
Update the password of the user This will update the password in the database, clear all sessions of the user and clear all cached fields, so getters throw until refresh()
verified()  : null|string
Get the users` verified date
verify()  : void
Verify the User This will write the verified timestamp to the database and clear all cached fields, so getters throw until refresh()
verifyPassword()  : bool
Verify a plaintext password against this user's stored credential and, on a correct match, transparently upgrade the stored hash when it is stale (rehash-on-login / onion peel). Self-healing.
verifyTwoFactorCode()  : bool
Check a code against the stored secret. Answers false while the account carries no secret, so a caller cannot tell enrollment states apart by it.
assertValidEmail()  : void
Make sure an email is a valid address that no other user has

Properties

$dbExpression

public static array<string|int, mixed> $dbExpression = []

$dbPermissionsObjectColumn

public static string $dbPermissionsObjectColumn = "user"

$dbPermissionsTable

public static string $dbPermissionsTable = "z_user_permission"

$dbTable

public static string $dbTable = "z_user"

Methods

__construct()

public __construct(array<string|int, mixed> $data) : mixed
Parameters
$data : array<string|int, mixed>
Return values
mixed —

add()

Create a new user This will insert the user into the database and return the created user object

public static add(string|null $email[, string|null $password = null ][, DateTime|null $verified = null ]) : User|null
Parameters
$email : string|null

The email of the new user, null creates a user without an email

$password : string|null = null

Optional the password of the new user (plain text, will be hashed)

$verified : DateTime|null = null

Optional datetime object indicating when the user was verified

Tags
throws
InvalidArgumentException

If the email is invalid or already used by another user, or the password is shorter than 3 or longer than 1024 bytes

Return values
User|null —

The created user object or null on failure

all()

Get a list of all active objects of the calling class (user, role, session, organization, API key)

public static all() : array<string|int, static>
Return values
array<string|int, static> —

The list of active objects

buildPermissionVariants()

Build permission variants for a given permission name

public static buildPermissionVariants(string $permissionName) : array<string|int, string>

e.g. "edit.article" => [".", "edit.", "edit.article.", "edit.article"]

Parameters
$permissionName : string

The permission name to build variants for

Return values
array<string|int, string> —

An array of permission variants

byAccessToAll()

public static byAccessToAll(string ...$permissionNames) : array<string|int, mixed>
Parameters
$permissionNames : string
Return values
array<string|int, mixed> —

byAccessToAnyOf()

public static byAccessToAnyOf(string ...$permissionNames) : array<string|int, mixed>
Parameters
$permissionNames : string
Return values
array<string|int, mixed> —

byEmail()

Get a user by their email address

public static byEmail(string $email) : User|null
Parameters
$email : string

The email address of the user

Return values
User|null —

The User object if found, null otherwise

byGroup()

public static byGroup(Group $group) : array<string|int, mixed>
Parameters
$group : Group
Return values
array<string|int, mixed> —

byId()

Get an object (user, role, session, organization or API key) by its id

public static byId(int|string $id) : static|null
Parameters
$id : int|string

the id of the object

Return values
static|null —

the object if found, null if the id is unknown or inactive

byIdentifier()

Get a permission object (user or role) by one of its identifiers

public static byIdentifier(string $column, int|string $identifier) : object|null
Parameters
$column : string

The identifying column, e.g. "id" or "uuid"

$identifier : int|string

The value of the identifying column

Return values
object|null —

the permission object if found, null otherwise

byIdentifiers()

Get a list of permission objects (user or role) by one of their identifiers

public static byIdentifiers(string $column, array<string|int, int>|array<string|int, string> $identifiers) : array<string|int, object>
Parameters
$column : string

The identifying column, e.g. "id" or "uuid"

$identifiers : array<string|int, int>|array<string|int, string>

The values of the identifying column

Return values
array<string|int, object> —

The list of permission objects

byIds()

Get a list of objects (user, role, session, organization or API key) by their ids Unknown or inactive ids are skipped, and calling it without ids throws a database exception

public static byIds(int ...$ids) : array<string|int, static>
Parameters
$ids : int

The ids of the objects to retrieve

Return values
array<string|int, static> —

the objects that were found

byNotVerified()

Get a list of users who were not verified as of the $since DateTime

public static byNotVerified(DateTime $since) : array<string|int, User>
Parameters
$since : DateTime

When to check for non-verified users

Return values
array<string|int, User> —

array of user objects

byOrganization()

public static byOrganization(Organization $organization) : array<string|int, mixed>
Parameters
$organization : Organization
Return values
array<string|int, mixed> —

byRole()

Get a list of users by a specific role, including members of organizations holding it

public static byRole(Role $role) : array<string|int, User>
Parameters
$role : Role

The role to filter users by

Return values
array<string|int, User> —

An array of User objects associated with the specified role

byUuid()

Get a permission object (user or role) by its uuid

public static byUuid(string $uuid) : object|null
Parameters
$uuid : string

the uuid of the object

Return values
object|null —

the permission object if found, null otherwise

byUuids()

Get a list of permission objects (user or role) by their uuids

public static byUuids(string ...$uuids) : array<string|int, object>
Parameters
$uuids : string

The uuids of the objects to retrieve

Return values
array<string|int, object> —

The list of permission objects

checkLoginTries()

public checkLoginTries() : bool
Return values
bool —

clearSessions()

Clear all sessions of the user

public clearSessions() : void
Return values
void —

confirmTwoFactor()

Finish an enrollment. Turning two factor on takes a code, which is what proves the secret reached the authenticator and was not lost in the page.

public confirmTwoFactor(string $code) : bool
Parameters
$code : string

The code from the authenticator

Return values
bool —

Whether the enrollment is now active

disableTwoFactor()

Drop two factor and the secret behind it

public disableTwoFactor() : void
Return values
void —

email()

Get the user's email from the cache

public email() : string|null
Return values
string|null —

The email of the user, null if none is set

getGroups()

Get the user's groups

public getGroups() : array<string|int, Group>
Return values
array<string|int, Group> —

Array of group objects

getPermissions()

Get the user's permissions including those inherited from roles

public getPermissions() : array<string|int, mixed>
Return values
array<string|int, mixed> —

getRoles()

Get the user's roles

public getRoles() : array<string|int, Role>
Return values
array<string|int, Role> —

Array of role objects

getUserPermissions()

Get the user's permissions

public getUserPermissions() : array<string|int, mixed>
Return values
array<string|int, mixed> —

groupsAdd()

Add Groups to the user This will add the groups automatically into the database and clear all cached fields, so getters throw until refresh()

public groupsAdd(array<string|int, Group> ...$groups) : void
Parameters
$groups : array<string|int, Group>

The groups to add to the user

Return values
void —

groupsRemove()

Remove groups from the user This will remove the groups automatically from the database and clear all cached fields, so getters throw until refresh()

public groupsRemove(array<string|int, Group> ...$groups) : void
Parameters
$groups : array<string|int, Group>

The groups to remove from the user

Return values
void —

hasAccessAll()

Check if the permission object (user or role) has all of the given permissions, wildcards count ("*.*" or "edit.*" cover "edit.article") and a user's permissions include those inherited from its roles

public hasAccessAll(array<string|int, string> ...$permissionNames) : bool
Parameters
$permissionNames : array<string|int, string>

The names of the permissions to check

Return values
bool —

True if the object has all of the permissions, false otherwise

hasAccessAnyOf()

Check if the permission object (user or role) has one of the permissions, wildcards included ("*.*" or "edit.*" cover "edit.article"); a user's role-inherited permissions count too

public hasAccessAnyOf(array<string|int, string> ...$permissionNames) : bool
Parameters
$permissionNames : array<string|int, string>

The names of the permissions to check

Return values
bool —

True if the object has at least one of the permissions, false otherwise

hasTwoFactor()

Whether two factor is active, which only a confirmed enrollment makes it.

public hasTwoFactor() : bool

A stored secret on its own is an enrollment nobody finished.

Return values
bool —

isVerified()

Check if a User is verified

public isVerified([string $at = "NOW" ]) : bool

A stored verification date that strtotime() cannot read counts as not verified.

Parameters
$at : string = "NOW"

"NOW" or any strtotime()-parseable datetime string (e.g. "2024-05-01 12:00:00") to check verification status at; unparsable values yield false (default: "NOW")

Return values
bool —

Returns true if the user is verified at the specified time, false otherwise

loadObject()

Re-/Loads the user object

public loadObject(array<string|int, mixed> $data) : void
Parameters
$data : array<string|int, mixed>

The data to load into the user object (in the format of a database row)

Return values
void —

permissionsAdd()

Add permissions to an permission object (user or role)

public permissionsAdd(array<string|int, string> ...$permissionNames) : void
Parameters
$permissionNames : array<string|int, string>

The names of the permissions to add

Return values
void —

permissionsRemove()

Remove permissions from the permission object (user or role)

public permissionsRemove(array<string|int, string> ...$permissionNames) : void
Parameters
$permissionNames : array<string|int, string>

The names of the permissions to remove

Return values
void —

recordLoginTry()

public recordLoginTry() : void
Return values
void —

refresh()

Refresh the current permission object (user, role, session, organization or API key) by clearing all its fields and setting them new

public refresh() : void
Tags
throws
InvalidArgumentException

If this instance was already detached

throws
RuntimeException

If the object no longer exists (its fields are already cleared by then)

Return values
void —

refreshAllPermissions()

Reload the user's direct and role-inherited permissions into the cache

public refreshAllPermissions() : void
Return values
void —

refreshPermissions()

Reload the user's directly assigned permissions (not role-inherited ones) into the cache

public refreshPermissions() : void
Return values
void —

remove()

Deactivate this user The instance is detached afterwards, so every later call on it throws InvalidArgumentException

public remove() : void
Return values
void —

rolesAdd()

Add roles to the user and clear all cached fields, so getters throw until refresh() This will add the roles automatically into the database

public rolesAdd(array<string|int, Role> ...$roles) : void
Parameters
$roles : array<string|int, Role>

The roles to add to the user

Return values
void —

rolesRemove()

Remove roles from the user and clear all cached fields, so getters throw until refresh() This will remove the roles automatically from the database

public rolesRemove(array<string|int, Role> ...$roles) : void
Parameters
$roles : array<string|int, Role>

The roles to remove from the user

Return values
void —

startTwoFactor()

Begin an enrollment by storing a fresh secret that does not count yet.

public startTwoFactor() : Totp

The returned object carries the secret and the provisioning uri, the two shapes an authenticator takes it in.

Return values
Totp —

The enrollment, to be shown once and never again

twoFactorConfirmedAt()

When the user confirmed their authenticator

public twoFactorConfirmedAt() : string|null
Return values
string|null —

The timestamp, or null while two factor is off

updateEmail()

Update the email address of the user This will update the email in the database and clear all cached fields, so getters throw until refresh()

public updateEmail(string|null $email) : void
Parameters
$email : string|null

The new email address, null clears the email

Tags
throws
InvalidArgumentException

If the email is invalid or already used by another user

Return values
void —

updateOrganization()

public updateOrganization(Organization|null $organization) : void
Parameters
$organization : Organization|null
Return values
void —

updatePassword()

Update the password of the user This will update the password in the database, clear all sessions of the user and clear all cached fields, so getters throw until refresh()

public updatePassword(string $password) : void
Parameters
$password : string

The new password

Tags
throws
InvalidArgumentException

If the password is shorter than 3 or longer than 1024 bytes

Return values
void —

verified()

Get the users` verified date

public verified() : null|string
Return values
null|string —

The users verified date or null if not verified

verify()

Verify the User This will write the verified timestamp to the database and clear all cached fields, so getters throw until refresh()

public verify([DateTime|null $date = null ]) : void
Parameters
$date : DateTime|null = null

Optional datetime object indicating when the user was verified. If null, current time will be used.

Return values
void —

verifyPassword()

Verify a plaintext password against this user's stored credential and, on a correct match, transparently upgrade the stored hash when it is stale (rehash-on-login / onion peel). Self-healing.

public verifyPassword(string $password) : bool

This is the password-check entry point for logging a user in. Only the database is upgraded; this instance's cached password, scheme and salt fields stay stale.

Parameters
$password : string

The plaintext password to check

Tags
throws
InvalidArgumentException

when a legacy/onion row has no salt.

Return values
bool —

Whether the password matched

verifyTwoFactorCode()

Check a code against the stored secret. Answers false while the account carries no secret, so a caller cannot tell enrollment states apart by it.

public verifyTwoFactorCode(string $code) : bool
Parameters
$code : string

The code from the authenticator

Return values
bool —

Whether the code matched

assertValidEmail()

Make sure an email is a valid address that no other user has

private static assertValidEmail(string|null $email[, int|null $ignoreUserId = null ]) : void
Parameters
$email : string|null

The email to check, null is always accepted

$ignoreUserId : int|null = null

A user whose own email does not count as taken

Tags
throws
InvalidArgumentException

If the email is invalid or already used by another user

Return values
void —

Search results