Manage cookies in a way that is syntactically and functionally similar
to the WebRequest#getCookie
and WebResponse#setcookie
methods in PHP.
Provided by the mediawiki.cookie ResourceLoader module.
- Source:
Example
mw.loader.using( 'mediawiki.cookie' ).then( () => {
mw.cookie.set('hello', 'world' );
})
Methods
get(key, prefixopt, defaultValueopt) → {string|null
}static
#
null
}static
#
Get the value of a cookie.
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
key |
string | |||
prefix |
string |
<optional> |
wgCookiePrefix | The prefix of the key. If |
defaultValue |
null
|
string
|
<optional> |
defaults to null |
- Source:
Returns:
If the cookie exists, then the value of the
cookie, otherwise defaultValue
- Type
-
string
|
null
getCrossSite(key, prefixopt, defaultValueopt) → {string|null
}static
#
null
}static
#
Get the value of a SameSite=None cookie, using the legacy ss0- cookie if needed.
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
key |
string | |||
prefix |
string |
<optional> |
wgCookiePrefix | The prefix of the key. If |
defaultValue |
null
|
string
|
<optional> |
- Source:
Returns:
If the cookie exists, then the value of the
cookie, otherwise defaultValue
- Type
-
string
|
null
set(key, value, optionsopt)static
#
Set or delete a cookie.
Note: If explicitly passing null
or undefined
for an options key,
that will override the default. This is natural in JavaScript, but noted
here because it is contrary to MediaWiki's WebResponse#setcookie()
method
in PHP.
When using this for persistent storage of identifiers (e.g. for tracking sessions), be aware that persistence may vary slightly across browsers and browser versions, and can be affected by a number of factors such as storage limits (cookie eviction) and session restore features.
Without an expiry, this creates a session cookie. In a browser, session cookies persist for the lifetime of the browser process. Including across tabs, page views, and windows, until the browser itself is fully closed, or until the browser clears all storage for a given website. An exception to this is if the user evokes a "restore previous session" feature that some browsers have.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
key |
string | ||
value |
string
|
null
|
Value of cookie. If |
|
options |
mw.cookie.CookieOptions | Date | number |
<optional> |
Options object, or expiry date |
- Source:
Type Definitions
CookieOptions
#
Custom scope for cookie key, must match the way it was set.
Type:
- Object
Properties:
Name | Type | Attributes | Description |
---|---|---|---|
path |
string |
<optional> |
The path attribute of the cookie. Defaults to wgCookiePath. |
prefix |
string |
<optional> |
The prefix of the key. Defaults to wgCookiePrefix. |
domain |
string |
<optional> |
Custom scope for cookie key. The domain attribute of the cookie. Defaults to wgCookieDomain. |
secure |
boolean |
<optional> |
Whether or not to include the secure attribute. Defaults to false. (Does not use the wgCookieSecure configuration variable) |
sameSite |
string |
<optional> |
The SameSite flag of the cookie ('None' / 'Lax' / 'Strict', case-insensitive; default is to omit the flag, which results in Lax on modern browsers). Set to None AND set secure=true if the cookie needs to be visible on cross-domain requests. |
sameSiteLegacy |
boolean |
<optional> |
Deprecated, ignored. |
expires |
Date
|
number
|
null
|
<optional> |
Number of days to store the value (when setting). The expiry date of the cookie, or lifetime in seconds. If null or 0, then a session cookie is set. Defaults to wgCookieExpiration. |
- Source: