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                  * Set or delete 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|number|null} [options.expires] The expiry date of the cookie, or lifetime in seconds.
  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                         // 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 ) {
  77                                 date = new Date();
  78                                 date.setTime( Number( date ) + ( config.wgCookieExpiration * 1000 ) );
  79                                 options.expires = date;
  80                         } else if ( typeof options.expires === 'number' ) {
  81                                 // Lifetime in seconds
  82                                 date = new Date();
  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;
  88                         }
  89
  90                         // Process prefix
  91                         key = options.prefix + key;
  92                         delete options.prefix;
  93
  94                         // Process value
  95                         if ( value !== null ) {
  96                                 value = String( value );
  97                         }
  98
  99                         // Other options are handled by $.cookie
 100                         $.cookie( key, value, options );
 101                 },
 102
 103                 /**
 104                  * Get the value of a cookie.
 105                  *
 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`
 112                  */
 113                 get: function ( key, prefix, defaultValue ) {
 114                         var result;
 115
 116                         if ( prefix === undefined || prefix === null ) {
 117                                 prefix = mw.config.get( 'wgCookiePrefix' );
 118                         }
 119
 120                         // Was defaultValue omitted?
 121                         if ( arguments.length < 3 ) {
 122                                 defaultValue = null;
 123                         }
 124
 125                         result = $.cookie( prefix + key );
 126
 127                         return result !== null ? result : defaultValue;
 128                 }
 129         };
 130
 131 }( mediaWiki, jQuery ) );