resources/src/mediawiki/mediawiki.cookie.js

   1 ( function ( mw, $ ) {
   2         'use strict';
   3
   4         /**
   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`).
   8          *
   9          * @author Sam Smith <samsmith@wikimedia.org>
  10          * @author Matthew Flaschen <mflaschen@wikimedia.org>
  11          * @author Timo Tijhof <krinklemail@gmail.com>
  12          *
  13          * @class mw.cookie
  14          * @singleton
  15          */
  16         mw.cookie = {
  17
  18                 /**
  19                  * Sets or deletes a cookie.
  20                  *
  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`).
  25                  *
  26                  * @param {string} key
  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] The expiry date of the cookie.
  31                  *
  32                  *   If `options.expires` is null, then a session cookie is set.
  33                  *
  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.
  37                  *
  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)
  43                  */
  44                 set: function ( key, value, options ) {
  45                         var config, defaultOptions, date;
  46
  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( [
  50                                 'wgCookiePrefix',
  51                                 'wgCookieDomain',
  52                                 'wgCookiePath',
  53                                 'wgCookieExpiration'
  54                         ] );
  55
  56                         defaultOptions = {
  57                                 prefix: config.wgCookiePrefix,
  58                                 domain: config.wgCookieDomain,
  59                                 path: config.wgCookiePath,
  60                                 secure: false
  61                         };
  62
  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;
  69                         } else {
  70                                 options = $.extend( defaultOptions, options );
  71                         }
  72
  73                         // $.cookie makes session cookies when expiry is omitted,
  74                         // however our default is to expire wgCookieExpiration seconds from now.
  75                         // Note: If wgCookieExpiration is 0, that is considered a special value indicating
  76                         // all cookies should be session cookies by default.
  77                         if ( options.expires === undefined && config.wgCookieExpiration !== 0 ) {
  78                                 date = new Date();
  79                                 date.setTime( Number( date ) + ( config.wgCookieExpiration * 1000 ) );
  80                                 options.expires = date;
  81                         } else if ( options.expires === null ) {
  82                                 // $.cookie makes a session cookie when expires is omitted
  83                                 delete options.expires;
  84                         }
  85
  86                         // Process prefix
  87                         key = options.prefix + key;
  88                         delete options.prefix;
  89
  90                         // Process value
  91                         if ( value !== null ) {
  92                                 value = String( value );
  93                         }
  94
  95                         // Other options are handled by $.cookie
  96                         $.cookie( key, value, options );
  97                 },
  98
  99                 /**
 100                  * Gets the value of a cookie.
 101                  *
 102                  * @param {string} key
 103                  * @param {string} [prefix=wgCookiePrefix] The prefix of the key. If `prefix` is
 104                  *   `undefined` or `null`, then `wgCookiePrefix` is used
 105                  * @param {Mixed} [defaultValue=null]
 106                  * @return {string} If the cookie exists, then the value of the
 107                  *   cookie, otherwise `defaultValue`
 108                  */
 109                 get: function ( key, prefix, defaultValue ) {
 110                         var result;
 111
 112                         if ( prefix === undefined || prefix === null ) {
 113                                 prefix = mw.config.get( 'wgCookiePrefix' );
 114                         }
 115
 116                         // Was defaultValue omitted?
 117                         if ( arguments.length < 3 ) {
 118                                 defaultValue = null;
 119                         }
 120
 121                         result = $.cookie( prefix + key );
 122
 123                         return result !== null ? result : defaultValue;
 124                 }
 125         };
 126
 127 } ( mediaWiki, jQuery ) );