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
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 —isMemberOf()
public
isMemberOf(Organization $organization) : bool
Parameters
- $organization : Organization
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 —organization()
public
organization() : Organization|null
Return values
Organization|null —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
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
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
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
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