SessionManager
in package
Opens, stores, resumes and refreshes users' sessions — `$discord->sessions`.
A session acts as one user with their own OAuth2 token: see Session.
Tokens given a key are kept in the token store (the tokenStore option), so
a session survives a restart; the most recently used sessions, up to a limit,
are also kept in memory.
Provisional accounts — Discord accounts for players who have not linked one —
are created here too, with the bot token. Exchanging an external identity
provider's token, unmerging by one, exchanging for a child application's
token, and refreshing an expired token all authenticate as the application
instead, and need the clientSecret option.
Tags
Table of Contents
Constants
- DEFAULT_LIMIT : mixed = 1000
- How many keyed sessions to keep in memory.
Properties
- $clientSecret : ?string
- $credentialsHttp : ?Http
- Sends no Authorization, for routes that take the application's credentials in the body.
- $discord : Discord
- $limit : int
- $sessions : array<string, Session>
- Keyed sessions, least recently used first.
- $store : TokenStoreInterface
Methods
- __construct() : mixed
- __debugInfo() : array<string, mixed>
- createProvisionalAccount() : PromiseInterface<string|int, Session>
- Creates a provisional account for a player in your own account system, or returns the one already made, and opens a session as it.
- exchangeChildToken() : PromiseInterface<string|int, Session>
- Exchanges a publisher application's token for one of its child applications' tokens, and opens a session as it.
- exchangeExternalToken() : PromiseInterface<string|int, Session>
- Exchanges a token from an external identity provider for a Discord token, creating a provisional account if needed, and opens a session as it.
- forget() : PromiseInterface<string|int, bool>
- Closes a keyed session and removes its token from the store.
- get() : ?Session
- Returns a keyed session that is already open, without touching the token store.
- open() : PromiseInterface<string|int, Session>
- Opens a session with a token, storing it under `$key` if one is given.
- refresh() : PromiseInterface<string|int, Session>
- Exchanges a session's refresh token for a new token, and stores it if the session is keyed.
- resume() : PromiseInterface<string|int, ?Session>
- Returns the session stored under `$key`, refreshing its token first if it has expired and can be refreshed.
- unmergeExternalAccount() : PromiseInterface
- Separates a provisional account from the Discord account it was merged into, identifying the player by an external provider's token.
- unmergeProvisionalAccount() : PromiseInterface
- Separates a provisional account from the Discord account it was merged into, using the bot token.
- credentialsHttp() : Http
- A client that sends no Authorization, sharing the bot's driver.
- remember() : Session
- Keeps a keyed session in memory as the most recently used, dropping the least recently used past the limit.
- withCredentials() : PromiseInterface
- Runs a call that authenticates as the application, once its id and secret are known.
Constants
DEFAULT_LIMIT
How many keyed sessions to keep in memory.
public
mixed
DEFAULT_LIMIT
= 1000
Properties
$clientSecret
protected
?string
$clientSecret
= null
$credentialsHttp
Sends no Authorization, for routes that take the application's credentials in the body.
protected
?Http
$credentialsHttp
= null
$discord
protected
Discord
$discord
$limit
protected
int
$limit
= self::DEFAULT_LIMIT
$sessions
Keyed sessions, least recently used first.
protected
array<string, Session>
$sessions
= []
$store
protected
TokenStoreInterface
$store
Methods
__construct()
public
__construct(Discord $discord, TokenStoreInterface $store[, string|null $clientSecret = null ][, int $limit = self::DEFAULT_LIMIT ]) : mixed
Parameters
- $discord : Discord
-
The client.
- $store : TokenStoreInterface
-
Where keyed tokens are kept.
- $clientSecret : string|null = null
-
The application's client secret, for refreshing and client-credential calls.
- $limit : int = self::DEFAULT_LIMIT
-
How many keyed sessions to keep in memory.
__debugInfo()
public
__debugInfo() : array<string, mixed>
Return values
array<string, mixed>createProvisionalAccount()
Creates a provisional account for a player in your own account system, or returns the one already made, and opens a session as it.
public
createProvisionalAccount(string $external_user_id[, string|null $preferred_global_name = null ][, string|null $key = null ]) : PromiseInterface<string|int, Session>
Uses the bot token. Provisional tokens cannot be refreshed; call this again for a new one when it expires.
Parameters
- $external_user_id : string
-
The player's unique id in your account system.
- $preferred_global_name : string|null = null
-
The player's display name in your system.
- $key : string|null = null
-
What to store the token under; not stored if omitted.
Tags
Return values
PromiseInterface<string|int, Session>exchangeChildToken()
Exchanges a publisher application's token for one of its child applications' tokens, and opens a session as it.
public
exchangeChildToken(Session|AccessToken $parent, string $child_application_id[, string|null $key = null ]) : PromiseInterface<string|int, Session>
The bot must be the publisher (parent) application; needs the clientSecret option. Child tokens cannot be refreshed.
Parameters
- $parent : Session|AccessToken
-
The publisher application's session or token for the player.
- $child_application_id : string
-
The game's application id.
- $key : string|null = null
-
What to store the child token under; not stored if omitted.
Tags
Return values
PromiseInterface<string|int, Session>exchangeExternalToken()
Exchanges a token from an external identity provider for a Discord token, creating a provisional account if needed, and opens a session as it.
public
exchangeExternalToken(string $external_auth_type, string $external_auth_token[, string|null $key = null ]) : PromiseInterface<string|int, Session>
Needs the clientSecret option, and the provider configured in the Developer Portal.
Parameters
- $external_auth_type : string
-
The provider type, such as
OIDC,STEAM_SESSION_TICKETorEPIC_ONLINE_SERVICES_ID_TOKEN. - $external_auth_token : string
-
The provider's token.
- $key : string|null = null
-
What to store the token under; not stored if omitted.
Tags
Return values
PromiseInterface<string|int, Session>forget()
Closes a keyed session and removes its token from the store.
public
forget(string $key) : PromiseInterface<string|int, bool>
Parameters
- $key : string
-
What the token is stored under.
Return values
PromiseInterface<string|int, bool>get()
Returns a keyed session that is already open, without touching the token store.
public
get(string $key) : ?Session
Parameters
- $key : string
-
What the token is stored under.
Return values
?Sessionopen()
Opens a session with a token, storing it under `$key` if one is given.
public
open(AccessToken|object|array<string|int, mixed> $token[, string|null $key = null ]) : PromiseInterface<string|int, Session>
Parameters
- $token : AccessToken|object|array<string|int, mixed>
-
A token, or a token response from Discord.
- $key : string|null = null
-
What to store the token under, such as your own user id; not stored if omitted.
Return values
PromiseInterface<string|int, Session>refresh()
Exchanges a session's refresh token for a new token, and stores it if the session is keyed.
public
refresh(Session $session) : PromiseInterface<string|int, Session>
Discord replaces the refresh token as well, and the old one stops working.
Parameters
- $session : Session
Tags
Return values
PromiseInterface<string|int, Session>resume()
Returns the session stored under `$key`, refreshing its token first if it has expired and can be refreshed.
public
resume(string $key) : PromiseInterface<string|int, ?Session>
Parameters
- $key : string
-
What the token is stored under.
Return values
PromiseInterface<string|int, ?Session> —Null if nothing is stored under the key.
unmergeExternalAccount()
Separates a provisional account from the Discord account it was merged into, identifying the player by an external provider's token.
public
unmergeExternalAccount(string $external_auth_type, string $external_auth_token) : PromiseInterface
Needs the clientSecret option.
Parameters
- $external_auth_type : string
-
The provider type.
- $external_auth_token : string
-
The provider's token.
Tags
Return values
PromiseInterfaceunmergeProvisionalAccount()
Separates a provisional account from the Discord account it was merged into, using the bot token.
public
unmergeProvisionalAccount(string $external_user_id) : PromiseInterface
Parameters
- $external_user_id : string
-
The player's unique id in your account system, as given to createProvisionalAccount().
Tags
Return values
PromiseInterfacecredentialsHttp()
A client that sends no Authorization, sharing the bot's driver.
protected
credentialsHttp() : Http
Return values
Httpremember()
Keeps a keyed session in memory as the most recently used, dropping the least recently used past the limit.
protected
remember(string $key, Session $session) : Session
Parameters
- $key : string
- $session : Session
Return values
SessionwithCredentials()
Runs a call that authenticates as the application, once its id and secret are known.
protected
withCredentials(callable(string, string): PromiseInterface $call) : PromiseInterface
Parameters
- $call : callable(string, string): PromiseInterface
-
Given the client id and secret.