classes/kohana/cookie.php

   1 <?php defined('SYSPATH') or die('No direct script access.');
   2 /**
   3  * Cookie helper.
   4  *
   5  * @package    Kohana
   6  * @category   Helpers
   7  * @author     Kohana Team
   8  * @copyright  (c) 2008-2010 Kohana Team
   9  * @license    http://kohanaframework.org/license
  10  */
  11 class Kohana_Cookie {
  12
  13         /**
  14          * @var  string  Magic salt to add to the cookie
  15          */
  16         public static $salt = NULL;
  17
  18         /**
  19          * @var  integer  Number of seconds before the cookie expires
  20          */
  21         public static $expiration = 0;
  22
  23         /**
  24          * @var  string  Restrict the path that the cookie is available to
  25          */
  26         public static $path = '/';
  27
  28         /**
  29          * @var  string  Restrict the domain that the cookie is available to
  30          */
  31         public static $domain = NULL;
  32
  33         /**
  34          * @var  boolean  Only transmit cookies over secure connections
  35          */
  36         public static $secure = FALSE;
  37
  38         /**
  39          * @var  boolean  Only transmit cookies over HTTP, disabling Javascript access
  40          */
  41         public static $httponly = FALSE;
  42
  43         /**
  44          * Gets the value of a signed cookie. Cookies without signatures will not
  45          * be returned. If the cookie signature is present, but invalid, the cookie
  46          * will be deleted.
  47          *
  48          *     // Get the "theme" cookie, or use "blue" if the cookie does not exist
  49          *     $theme = Cookie::get('theme', 'blue');
  50          *
  51          * @param   string  cookie name
  52          * @param   mixed   default value to return
  53          * @return  string
  54          */
  55         public static function get($key, $default = NULL)
  56         {
  57                 if ( ! isset($_COOKIE[$key]))
  58                 {
  59                         // The cookie does not exist
  60                         return $default;
  61                 }
  62
  63                 // Get the cookie value
  64                 $cookie = $_COOKIE[$key];
  65
  66                 // Find the position of the split between salt and contents
  67                 $split = strlen(Cookie::salt($key, NULL));
  68
  69                 if (isset($cookie[$split]) AND $cookie[$split] === '~')
  70                 {
  71                         // Separate the salt and the value
  72                         list ($hash, $value) = explode('~', $cookie, 2);
  73
  74                         if (Cookie::salt($key, $value) === $hash)
  75                         {
  76                                 // Cookie signature is valid
  77                                 return $value;
  78                         }
  79
  80                         // The cookie signature is invalid, delete it
  81                         Cookie::delete($key);
  82                 }
  83
  84                 return $default;
  85         }
  86
  87         /**
  88          * Sets a signed cookie. Note that all cookie values must be strings and no
  89          * automatic serialization will be performed!
  90          *
  91          *     // Set the "theme" cookie
  92          *     Cookie::set('theme', 'red');
  93          *
  94          * @param   string   name of cookie
  95          * @param   string   value of cookie
  96          * @param   integer  lifetime in seconds
  97          * @return  boolean
  98          * @uses    Cookie::salt
  99          */
 100         public static function set($name, $value, $expiration = NULL)
 101         {
 102                 if ($expiration === NULL)
 103                 {
 104                         // Use the default expiration
 105                         $expiration = Cookie::$expiration;
 106                 }
 107
 108                 if ($expiration !== 0)
 109                 {
 110                         // The expiration is expected to be a UNIX timestamp
 111                         $expiration += time();
 112                 }
 113
 114                 // Add the salt to the cookie value
 115                 $value = Cookie::salt($name, $value).'~'.$value;
 116
 117                 return setcookie($name, $value, $expiration, Cookie::$path, Cookie::$domain, Cookie::$secure, Cookie::$httponly);
 118         }
 119
 120         /**
 121          * Deletes a cookie by making the value NULL and expiring it.
 122          *
 123          *     Cookie::delete('theme');
 124          *
 125          * @param   string   cookie name
 126          * @return  boolean
 127          * @uses    Cookie::set
 128          */
 129         public static function delete($name)
 130         {
 131                 // Remove the cookie
 132                 unset($_COOKIE[$name]);
 133
 134                 // Nullify the cookie and make it expire
 135                 return Cookie::set($name, NULL, -86400);
 136         }
 137
 138         /**
 139          * Generates a salt string for a cookie based on the name and value.
 140          *
 141          *     $salt = Cookie::salt('theme', 'red');
 142          *
 143          * @param   string   name of cookie
 144          * @param   string   value of cookie
 145          * @return  string
 146          */
 147         public static function salt($name, $value)
 148         {
 149                 // Require a valid salt
 150                 if ( ! Cookie::$salt)
 151                 {
 152                         throw new Kohana_Exception('A valid cookie salt is required. Please set Cookie::$salt.');
 153                 }
 154
 155                 // Determine the user agent
 156                 $agent = isset($_SERVER['HTTP_USER_AGENT']) ? strtolower($_SERVER['HTTP_USER_AGENT']) : 'unknown';
 157
 158                 return sha1($agent.$name.$value.Cookie::$salt);
 159         }
 160
 161 } // End cookie