resources/src/mediawiki.cookie/index.js

   1 'use strict';
   2
   3 var config = require( './config.json' ),
   4         defaults = {
   5                 prefix: config.prefix,
   6                 domain: config.domain,
   7                 path: config.path,
   8                 expires: config.expires,
   9                 secure: false
  10         };
  11
  12 /**
  13  * Manage cookies in a way that is syntactically and functionally similar
  14  * to the `WebRequest#getCookie` and `WebResponse#setcookie` methods in PHP.
  15  *
  16  * @author Sam Smith <samsmith@wikimedia.org>
  17  * @author Matthew Flaschen <mflaschen@wikimedia.org>
  18  *
  19  * @class mw.cookie
  20  * @singleton
  21  */
  22 mw.cookie = {
  23
  24         /**
  25          * Set or delete a cookie.
  26          *
  27          * **Note:** If explicitly passing `null` or `undefined` for an options key,
  28          * that will override the default. This is natural in JavaScript, but noted
  29          * here because it is contrary to MediaWiki's `WebResponse#setcookie()` method
  30          * in PHP.
  31          *
  32          * @param {string} key
  33          * @param {string|null} value Value of cookie. If `value` is `null` then this method will
  34          *   instead remove a cookie by name of `key`.
  35          * @param {Object|Date|number} [options] Options object, or expiry date
  36          * @param {Date|number|null} [options.expires=wgCookieExpiration] The expiry date of the cookie,
  37          *  or lifetime in seconds. If `options.expires` is null or 0, then a session cookie is set.
  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 date;
  46
  47                 // The 'options' parameter may be a shortcut for the expiry.
  48                 if ( arguments.length > 2 && ( !options || options instanceof Date || typeof options === 'number' ) ) {
  49                         options = { expires: options };
  50                 }
  51                 // Apply defaults
  52                 options = $.extend( {}, defaults, options );
  53
  54                 // Handle prefix
  55                 key = options.prefix + key;
  56                 // Don't pass invalid option to $.cookie
  57                 delete options.prefix;
  58
  59                 if ( !options.expires ) {
  60                         // Session cookie (null or zero)
  61                         // Normalize to absent (undefined) for $.cookie.
  62                         delete options.expires;
  63                 } else if ( typeof options.expires === 'number' ) {
  64                         // Lifetime in seconds
  65                         date = new Date();
  66                         date.setTime( Number( date ) + ( options.expires * 1000 ) );
  67                         options.expires = date;
  68                 }
  69
  70                 if ( value !== null ) {
  71                         value = String( value );
  72                 }
  73
  74                 $.cookie( key, value, options );
  75         },
  76
  77         /**
  78          * Get the value of a cookie.
  79          *
  80          * @param {string} key
  81          * @param {string} [prefix=wgCookiePrefix] The prefix of the key. If `prefix` is
  82          *   `undefined` or `null`, then `wgCookiePrefix` is used
  83          * @param {Mixed} [defaultValue=null]
  84          * @return {string|null|Mixed} If the cookie exists, then the value of the
  85          *   cookie, otherwise `defaultValue`
  86          */
  87         get: function ( key, prefix, defaultValue ) {
  88                 var result;
  89
  90                 if ( prefix === undefined || prefix === null ) {
  91                         prefix = defaults.prefix;
  92                 }
  93
  94                 // Was defaultValue omitted?
  95                 if ( arguments.length < 3 ) {
  96                         defaultValue = null;
  97                 }
  98
  99                 result = $.cookie( prefix + key );
 100
 101                 return result !== null ? result : defaultValue;
 102         }
 103 };
 104
 105 if ( window.QUnit ) {
 106         module.exports = {
 107                 setDefaults: function ( value ) {
 108                         var prev = defaults;
 109                         defaults = value;
 110                         return prev;
 111                 }
 112         };
 113 }