Expand all

mediawiki.cookie

Manage cookies in a way that is syntactically and functionally similar to the WebRequest#getCookie and WebResponse#setcookie methods in PHP.

Example

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

Methods

$.cookie([key], [value], [options]) → {string|Object}static #

Set a cookie.

To use this jQuery plugin, load the mediawiki.cookie module using mw.loader.

Example

mw.loader.using( 'mediawiki.cookie' ).then( () => {
    $.cookie( 'name', 'value', {} );
} );

Parameters:

Name Type Attributes Description
key string optional

Cookie name or (when getting) omit to return an object with all current cookie keys and values.
value string | null optional

Cookie value to set. If null, this method will remove the cookie. If omited, this method will get and return the current value.
options module:mediawiki.cookie~CookieOptions optional
Source:

Returns:

The current value (if getting a cookie), or an internal document.cookie expression (if setting or removing).

Type
string | Object
Set a cookie.

$.removeCookie(key, options) → {boolean}static #

Remove a cookie by key.

To use this jQuery plugin, load the mediawiki.cookie module using mw.loader.

Example

mw.loader.using( 'mediawiki.cookie' ).then( () => {
    $.removeCookie( 'name', {} );
} );

Parameters:

Name Type Description
key string
options module:mediawiki.cookie~CookieOptions
Source:

Returns:

True if the cookie previously existed

Type
boolean
Remove a cookie by key.

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 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
Deprecated:
Source:

Returns:

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

Type
string | null
Get the value of a cookie.

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 module:mediawiki.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.