Documentation

Role extends AuthenticationEntity
in package
Uses Permission, RetrievalTrait, HandleTrait

Table of Contents

$dbPermissionsObjectColumn  : string
$dbPermissionsTable  : string
$dbTable  : string
$dbExpression  : array<string|int, mixed>
__construct()  : mixed
add()  : Role
Create a new Role This will insert the role into the database and return the created Role 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>
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
byName()  : Role|null
Get a Role by its name
byOrganization()  : array<string|int, mixed>
byUser()  : array<string|int, Role>
Get a list of Roles by User, including the roles of its organization
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
getPermissions()  : array<string|int, string>
Get Permissions which are associated with this Role
getUsers()  : array<string|int, User>
Get Users with this Role
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
loadObject()  : void
Re-/Loads the Role Object
name()  : string
Get the Roles name from the cache
permissionsAdd()  : void
Add permissions to an permission object (user or role)
permissionsRemove()  : void
Remove permissions from the permission object (user or role)
refresh()  : void
Refresh the current permission object (user, role, session, organization or API key) by clearing all its fields and setting them new
refreshPermissions()  : void
Reset the Permissions Cache
remove()  : void
Remove the Role This will deactivate the Role in the Database The instance is detached afterwards, so every later call on it throws InvalidArgumentException
setPermissionsByRole()  : void
Replace this Role's permissions with the permissions of another Role.
update()  : void
Rename the Role Clears the cached fields, so name() and other getters throw until refresh() is called
refreshUsers()  : void
Reset the Users Cache

Properties

$dbPermissionsObjectColumn

public static string $dbPermissionsObjectColumn = "role"

$dbPermissionsTable

public static string $dbPermissionsTable = "z_role_permission"

$dbTable

public static string $dbTable = "z_role"

$dbExpression

private static array<string|int, mixed> $dbExpression = ["zr.is_group" => 0]

Methods

__construct()

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

add()

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

public static add(string $rolename) : Role
Parameters
$rolename : string

The name of the new role

Return values
Role —

The created Role object

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> —

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

byName()

Get a Role by its name

public static byName(string $name) : Role|null
Parameters
$name : string

The name of the role

Return values
Role|null —

The Role object if found, null otherwise

byOrganization()

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

byUser()

Get a list of Roles by User, including the roles of its organization

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

The user to filter roles by

Return values
array<string|int, Role> —

An array of Role objects associated with the specified user

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

getPermissions()

Get Permissions which are associated with this Role

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

The permissions associated with this role

getUsers()

Get Users with this Role

public getUsers() : array<string|int, User>
Return values
array<string|int, User> —

The users with this role

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

loadObject()

Re-/Loads the Role Object

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

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

Return values
void —

name()

Get the Roles name from the cache

public name() : string
Return values
string —

The name of the Role

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 —

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 —

refreshPermissions()

Reset the Permissions Cache

public refreshPermissions() : void
Return values
void —

remove()

Remove the Role This will deactivate the Role in the Database The instance is detached afterwards, so every later call on it throws InvalidArgumentException

public remove() : void
Return values
void —

setPermissionsByRole()

Replace this Role's permissions with the permissions of another Role.

public setPermissionsByRole(Role $role) : void

Removes all currently assigned permissions and copies the source Role's permissions over.

Parameters
$role : Role

The role whose permissions should be adopted

Return values
void —

update()

Rename the Role Clears the cached fields, so name() and other getters throw until refresh() is called

public update(string $newName) : void
Parameters
$newName : string

The new name for the role

Return values
void —

refreshUsers()

Reset the Users Cache

private refreshUsers() : void
Return values
void —

Search results