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=wgCookieExpiration] The expiry date of the cookie.
  31                  *
  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.
  35                  *
  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)
  42                  */
  43                 set: function ( key, value, options ) {
  44                         var config, defaultOptions, date;
  45
  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( [
  49                                 'wgCookiePrefix',
  50                                 'wgCookieDomain',
  51                                 'wgCookiePath',
  52                                 'wgCookieExpiration'
  53                         ] );
  54
  55                         defaultOptions = {
  56                                 prefix: config.wgCookiePrefix,
  57                                 domain: config.wgCookieDomain,
  58                                 path: config.wgCookiePath,
  59                                 secure: false
  60                         };
  61
  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;
  68                         } else {
  69                                 options = $.extend( defaultOptions, options );
  70                         }
  71
  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 ) {
  77                                 date = new Date();
  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;
  83                         }
  84
  85                         // Process prefix
  86                         key = options.prefix + key;
  87                         delete options.prefix;
  88
  89                         // Process value
  90                         if ( value !== null ) {
  91                                 value = String( value );
  92                         }
  93
  94                         // Other options are handled by $.cookie
  95                         $.cookie( key, value, options );
  96                 },
  97
  98                 /**
  99                  * Gets the value of a cookie.
 100                  *
 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`
 107                  */
 108                 get: function ( key, prefix, defaultValue ) {
 109                         var result;
 110
 111                         if ( prefix === undefined || prefix === null ) {
 112                                 prefix = mw.config.get( 'wgCookiePrefix' );
 113                         }
 114
 115                         // Was defaultValue omitted?
 116                         if ( arguments.length < 3 ) {
 117                                 defaultValue = null;
 118                         }
 119
 120                         result = $.cookie( prefix + key );
 121
 122                         return result !== null ? result : defaultValue;
 123                 }
 124         };
 125
 126 } ( mediaWiki, jQuery ) );