5 * Provides an API for getting and setting cookies that is
6 * syntactically and functionally similar to the server-side cookie
7 * API (`WebRequest#getCookie` and `WebResponse#setcookie`).
9 * @author Sam Smith <samsmith@wikimedia.org>
10 * @author Matthew Flaschen <mflaschen@wikimedia.org>
11 * @author Timo Tijhof <krinklemail@gmail.com>
19 * Sets or deletes a cookie.
21 * While this is natural in JavaScript, contrary to `WebResponse#setcookie` in PHP, the
22 * default values for the `options` properties only apply if that property isn't set
23 * already in your options object (e.g. passing `{ secure: null }` or `{ secure: undefined }`
24 * overrides the default value for `options.secure`).
27 * @param {string|null} value Value of cookie. If `value` is `null` then this method will
28 * instead remove a cookie by name of `key`.
29 * @param {Object|Date} [options] Options object, or expiry date
30 * @param {Date|null} [options.expires=wgCookieExpiration] The expiry date of the cookie.
32 * Default cookie expiration is based on `wgCookieExpiration`. If `wgCookieExpiration` is
33 * 0, a session cookie is set (expires when the browser is closed). For non-zero values of
34 * `wgCookieExpiration`, the cookie expires `wgCookieExpiration` seconds from now.
36 * If options.expires is null, then a session cookie is set.
37 * @param {string} [options.prefix=wgCookiePrefix] The prefix of the key
38 * @param {string} [options.domain=wgCookieDomain] The domain attribute of the cookie
39 * @param {string} [options.path=wgCookiePath] The path attribute of the cookie
40 * @param {boolean} [options.secure=false] Whether or not to include the secure attribute.
41 * (Does **not** use the wgCookieSecure configuration variable)
43 set: function ( key
, value
, options
) {
44 var config
, defaultOptions
, date
;
46 // wgCookieSecure is not used for now, since 'detect' could not work with
47 // ResourceLoaderStartUpModule, as module cache is not fragmented by protocol.
48 config
= mw
.config
.get( [
56 prefix
: config
.wgCookiePrefix
,
57 domain
: config
.wgCookieDomain
,
58 path
: config
.wgCookiePath
,
62 // Options argument can also be a shortcut for the expiry
63 // Expiry can be a Date or null
64 if ( $.type( options
) !== 'object' ) {
65 // Also takes care of options = undefined, in which case we also don't need $.extend()
66 defaultOptions
.expires
= options
;
67 options
= defaultOptions
;
69 options
= $.extend( defaultOptions
, options
);
72 // $.cookie makes session cookies when expiry is omitted,
73 // however our default is to expire wgCookieExpiration seconds from now.
74 // Note: If wgCookieExpiration is 0, that is considered a special value indicating
75 // all cookies should be session cookies by default.
76 if ( options
.expires
=== undefined && config
.wgCookieExpiration
!== 0 ) {
78 date
.setTime( Number( date
) + ( config
.wgCookieExpiration
* 1000 ) );
79 options
.expires
= date
;
80 } else if ( options
.expires
=== null ) {
81 // $.cookie makes a session cookie when expires is omitted
82 delete options
.expires
;
86 key
= options
.prefix
+ key
;
87 delete options
.prefix
;
90 if ( value
!== null ) {
91 value
= String( value
);
94 // Other options are handled by $.cookie
95 $.cookie( key
, value
, options
);
99 * Gets the value of a cookie.
101 * @param {string} key
102 * @param {string} [prefix=wgCookiePrefix] The prefix of the key. If `prefix` is
103 * `undefined` or `null`, then `wgCookiePrefix` is used
104 * @param {Mixed} [defaultValue=null]
105 * @return {string} If the cookie exists, then the value of the
106 * cookie, otherwise `defaultValue`
108 get: function ( key
, prefix
, defaultValue
) {
111 if ( prefix
=== undefined || prefix
=== null ) {
112 prefix
= mw
.config
.get( 'wgCookiePrefix' );
115 // Was defaultValue omitted?
116 if ( arguments
.length
< 3 ) {
120 result
= $.cookie( prefix
+ key
);
122 return result
!== null ? result
: defaultValue
;
126 } ( mediaWiki
, jQuery
) );