5923ff8fccbfc263ac556fde3d2fb4253dc1e843
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 * Set or delete 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|number|null} [options.expires] The expiry date of the cookie, or lifetime in seconds.
32 * If `options.expires` is null, then a session cookie is set.
34 * By default cookie expiration is based on `wgCookieExpiration`. Similar to `WebResponse`
35 * in PHP, we set a session cookie if `wgCookieExpiration` is 0. And for non-zero values
36 * it is interpreted as lifetime in seconds.
38 * @param {string} [options.prefix=wgCookiePrefix] The prefix of the key
39 * @param {string} [options.domain=wgCookieDomain] The domain attribute of the cookie
40 * @param {string} [options.path=wgCookiePath] The path attribute of the cookie
41 * @param {boolean} [options.secure=false] Whether or not to include the secure attribute.
42 * (Does **not** use the wgCookieSecure configuration variable)
44 set: function ( key
, value
, options
) {
45 var config
, defaultOptions
, date
;
47 // wgCookieSecure is not used for now, since 'detect' could not work with
48 // ResourceLoaderStartUpModule, as module cache is not fragmented by protocol.
49 config
= mw
.config
.get( [
57 prefix
: config
.wgCookiePrefix
,
58 domain
: config
.wgCookieDomain
,
59 path
: config
.wgCookiePath
,
63 // Options argument can also be a shortcut for the expiry
64 // Expiry can be a Date or null
65 if ( $.type( options
) !== 'object' ) {
66 // Also takes care of options = undefined, in which case we also don't need $.extend()
67 defaultOptions
.expires
= options
;
68 options
= defaultOptions
;
70 options
= $.extend( defaultOptions
, options
);
73 // Default to using wgCookieExpiration (lifetime in seconds).
74 // 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 ( typeof options
.expires
=== 'number' ) {
81 // Lifetime in seconds
83 date
.setTime( Number( date
) + ( options
.expires
* 1000 ) );
84 options
.expires
= date
;
85 } else if ( options
.expires
=== null ) {
86 // $.cookie makes a session cookie when options.expires is omitted
87 delete options
.expires
;
91 key
= options
.prefix
+ key
;
92 delete options
.prefix
;
95 if ( value
!== null ) {
96 value
= String( value
);
99 // Other options are handled by $.cookie
100 $.cookie( key
, value
, options
);
104 * Get the value of a cookie.
106 * @param {string} key
107 * @param {string} [prefix=wgCookiePrefix] The prefix of the key. If `prefix` is
108 * `undefined` or `null`, then `wgCookiePrefix` is used
109 * @param {Mixed} [defaultValue=null]
110 * @return {string|null|Mixed} If the cookie exists, then the value of the
111 * cookie, otherwise `defaultValue`
113 get: function ( key
, prefix
, defaultValue
) {
116 if ( prefix
=== undefined || prefix
=== null ) {
117 prefix
= mw
.config
.get( 'wgCookiePrefix' );
120 // Was defaultValue omitted?
121 if ( arguments
.length
< 3 ) {
125 result
= $.cookie( prefix
+ key
);
127 return result
!== null ? result
: defaultValue
;