mw.cookie

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.

Example

mw.loader.using( 'mediawiki.cookie' ).then( () => {
  mw.cookie.set('hello', 'world' );
})

Methods

get(key, prefix, defaultValue) → {string|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 prefix is undefined or null, then wgCookiePrefix is used
defaultValue null | string optional

defaults to null
Source:

Returns:

If the cookie exists, then the value of the cookie, otherwise defaultValue

Type
string | null
Get the value of a cookie.

getCrossSite(key, prefix, defaultValue) → {string|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 prefix is undefined or null, then wgCookiePrefix is used
defaultValue null | string optional
Source:

Returns:

If the cookie exists, then the value of the cookie, otherwise defaultValue

Type
string | null
Get the value of a SameSite=None cookie, using the legacy ss0- cookie if needed.

set(key, value, options)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 value is null then this method will instead remove a cookie by name of key.
options mw.cookie.CookieOptions | Date | number optional

Options object, or expiry date
Source:
Set or delete a cookie.

Type Definitions

CookieOptions #

Custom scope for cookie key, must match the way it was set.

Type:

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:
Custom scope for cookie key, must match the way it was set.