Documentation

Session extends AuthenticationEntity
in package
Uses CanUseSession, HandleTrait, RetrievalTrait

Table of Contents

$dbExpression  : array<string|int, mixed>
$dbTable  : string
$shouldRefresh  : bool
$token  : string|null
__construct()  : mixed
add()  : Session
all()  : array<string|int, static>
Get a list of all active objects of the calling class (user, role, session, organization, API key)
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
byToken()  : Session|APIKey|null
A session by its token, whichever kind the token opens
byUser()  : array<string|int, static>
All active sessions of a user, of the kind the called class stands for
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
canExpire()  : bool
Whether the session is subject to expiring at all
clearForUser()  : void
created()  : string|null
device()  : string|null
The user agent the session was started from, or null when none was sent
expiresAt()  : string|null
The point in time the session becomes unusable, or null when it cannot expire
extend()  : void
extendedSeconds()  : int|null
invalidate()  : void
ipCreation()  : string|null
The address the session was created from, or null when it was not known
ipLast()  : string|null
The address the session was last used from, or null while it is unused
isExpired()  : bool
lastTwoFactor()  : string|null
When this session last passed a two factor check, or null while it never did
lastUsed()  : string|null
When the session was last used, or null while it is unused
loadObject()  : mixed
name()  : string|null
reason()  : string|null
Why the session was created, e.g. an impersonation, or null
recordTwoFactor()  : void
Stamps a freshly passed two factor check on the session
refresh()  : void
Refresh the current permission object (user, role, session, organization or API key) by clearing all its fields and setting them new
remainingTwoFactorTries()  : int
How many wrong two factor codes this session may still send. At zero it is signed out rather than asked again.
requireRenew()  : bool
Whether this session has to pass two factor again before it is let near a guarded action.
resetTwoFactorTries()  : void
Hands the session its full budget of two factor tries back
setCanExpire()  : void
Subjects the session to expiring, or exempts it from it. A session that cannot expire is not invalidated on use, so an already expired one becomes usable again by turning this off.
setExpiresAt()  : void
Fixes the point in time the session expires, or hands it back to the computed lifetime when null is passed. A fixed expiry replaces that lifetime, so extending the session no longer moves it.
setExtensionTime()  : void
setName()  : void
Names the session, or removes its name when null is passed
spendTwoFactorTry()  : int
Spends one of the tries on a wrong code and answers how many are left
storedToken()  : string
token()  : string|null
userId()  : int|null
userIdExec()  : int|null
refreshOnNextUse()  : void

Properties

$dbExpression

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

Methods

__construct()

public __construct(array<string|int, mixed> $data[, string|null $token = null ]) : mixed
Parameters
$data : array<string|int, mixed>
$token : string|null = null
Return values
mixed —

add()

public static add(User $user[, User|null $userExec = null ][, string|null $name = null ][, string|null $reason = null ]) : Session
Parameters
$user : User
$userExec : User|null = null
$name : string|null = null
$reason : string|null = null
Return values
Session —

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

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

byToken()

A session by its token, whichever kind the token opens

public static byToken(string $token) : Session|APIKey|null

A token does not say what it opens, so the row picks the class. This is the entry point of the authentication, which has to resolve both kinds - an api key must not be measured against the login timeout.

Parameters
$token : string
Return values
Session|APIKey|null —

byUser()

All active sessions of a user, of the kind the called class stands for

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

The user whose sessions are returned

Return values
array<string|int, static> —

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

canExpire()

Whether the session is subject to expiring at all

public canExpire() : bool
Return values
bool —

clearForUser()

public static clearForUser(User $user) : void
Parameters
$user : User
Return values
void —

created()

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

device()

The user agent the session was started from, or null when none was sent

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

expiresAt()

The point in time the session becomes unusable, or null when it cannot expire

public expiresAt([bool $refresh = true ]) : string|null

A fixed expiry wins over the computed lifetime, so neither the configured timeout nor an extension has a say once one is set. A session that cannot expire outranks both - it never becomes unusable at all.

Parameters
$refresh : bool = true
Return values
string|null —

extend()

public extend(int $seconds) : void
Parameters
$seconds : int
Return values
void —

extendedSeconds()

public extendedSeconds() : int|null
Return values
int|null —

invalidate()

public invalidate() : void
Return values
void —

ipCreation()

The address the session was created from, or null when it was not known

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

ipLast()

The address the session was last used from, or null while it is unused

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

isExpired()

public isExpired() : bool
Return values
bool —

lastTwoFactor()

When this session last passed a two factor check, or null while it never did

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

lastUsed()

When the session was last used, or null while it is unused

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

loadObject()

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

name()

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

reason()

Why the session was created, e.g. an impersonation, or null

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

recordTwoFactor()

Stamps a freshly passed two factor check on the session

public recordTwoFactor() : 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 —

remainingTwoFactorTries()

How many wrong two factor codes this session may still send. At zero it is signed out rather than asked again.

public remainingTwoFactorTries() : int
Return values
int —

requireRenew()

Whether this session has to pass two factor again before it is let near a guarded action.

public requireRenew([int|null $freshnessSeconds = null ]) : bool

False for an account that carries no two factor - there is nothing to renew and the visitor could never satisfy it. Otherwise true while the session never passed a check, or once the last one aged past two_factor_freshness_seconds. An api key starts without a stamp, so it stays stale for an account with two factor until it passes a renewal.

Parameters
$freshnessSeconds : int|null = null
Return values
bool —

resetTwoFactorTries()

Hands the session its full budget of two factor tries back

public resetTwoFactorTries() : void
Return values
void —

setCanExpire()

Subjects the session to expiring, or exempts it from it. A session that cannot expire is not invalidated on use, so an already expired one becomes usable again by turning this off.

public setCanExpire(bool $canExpire) : void

The column stores the exemption, so it is inverted here once.

Parameters
$canExpire : bool
Return values
void —

setExpiresAt()

Fixes the point in time the session expires, or hands it back to the computed lifetime when null is passed. A fixed expiry replaces that lifetime, so extending the session no longer moves it.

public setExpiresAt(DateTime|null $expiresAt) : void
Parameters
$expiresAt : DateTime|null
Return values
void —

setExtensionTime()

public setExtensionTime(int $seconds) : void
Parameters
$seconds : int
Return values
void —

setName()

Names the session, or removes its name when null is passed

public setName(string|null $name) : void
Parameters
$name : string|null
Return values
void —

spendTwoFactorTry()

Spends one of the tries on a wrong code and answers how many are left

public spendTwoFactorTry() : int
Return values
int —

storedToken()

public storedToken() : string
Return values
string —

token()

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

userId()

public userId() : int|null
Return values
int|null —

userIdExec()

public userIdExec() : int|null
Return values
int|null —

refreshOnNextUse()

protected refreshOnNextUse() : void
Return values
void —

Search results