resources/src/mediawiki.cookie/index.js

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