SessionManager
in package
Opens, stores, resumes, refreshes and revokes 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.
- exchangeAuthorizationCode() : PromiseInterface<string|int, Session>
- Exchanges an authorization code for a user's token and opens a session as them.
- 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.
- getPublicKeys() : PromiseInterface<string|int, array<int, array<string, mixed>>>
- Returns the public keys that sign Discord's OpenID Connect ID tokens, as the `keys` of a JSON Web Key Set, ready to give a JWT library to verify an ID token with. They need no token to read.
- 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.
- revoke() : PromiseInterface<string|int, bool>
- Revokes a user's OAuth2 authorization at Discord, then forgets this session's stored token.
- 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>exchangeAuthorizationCode()
Exchanges an authorization code for a user's token and opens a session as them.
public
exchangeAuthorizationCode(string $code, string $redirect_uri[, string|null $key = null ]) : PromiseInterface<string|int, Session>
For confidential clients: requires the clientSecret option. The caller must validate the
authorization callback's state before calling this, and handle a denied authorization.
Parameters
- $code : string
-
The authorization code returned by Discord.
- $redirect_uri : string
-
The exact redirect URI used for the authorization request.
- $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
?SessiongetPublicKeys()
Returns the public keys that sign Discord's OpenID Connect ID tokens, as the `keys` of a JSON Web Key Set, ready to give a JWT library to verify an ID token with. They need no token to read.
public
getPublicKeys() : PromiseInterface<string|int, array<int, array<string, mixed>>>
Discord describes this endpoint in its OpenAPI description rather than in its documentation.
Tags
Return values
PromiseInterface<string|int, array<int, array<string, mixed>>>open()
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. Known provisional and child origins reject without a request; repeat their issuance instead.
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.
Tags
Return values
PromiseInterface<string|int, ?Session> —Null if nothing is stored under the key.
revoke()
Revokes a user's OAuth2 authorization at Discord, then forgets this session's stored token.
public
revoke(Session $session) : PromiseInterface<string|int, bool>
Discord invalidates all access and refresh tokens for the authorization, not only this token.
The caller must also clear their account mapping and any other local keys for that user.
Requires the clientSecret option. On HTTP failure the local session and token are retained.
Retained Session objects must no longer be used after a successful revocation.
Parameters
- $session : Session
-
The session whose authorization to revoke.
Tags
Return values
PromiseInterface<string|int, bool> —True for an unkeyed session, otherwise the token store's deletion result.
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.