<?php namespace Laravel; defined('DS') or die('No direct script access.');
use Closure;
// Cookie类
class Cookie {
/**
* The cookies that have been set.
* 已设置的cookie
* @var array
*/
public static $jar = array();
/**
* Determine if a cookie exists.
* 判断一个cookie是否存在
* @param string $name
* @return bool
*/
public static function has($name)
{
return ! is_null(static::get($name));
}
/**
* Send all of the cookies to the browser.
* 发送cookie到浏览器
* @return void
*/
public static function send()
{
// headers_sent() 检测HTTP头是否已经发送
if (headers_sent()) return false;
// All cookies are stored in the "jar" when set and not sent directly to the
// browser. This simply makes testing all of the cookie stuff very easy
// since the jar can be inspected by the tests.
// 当设置后, 所有的cookies都将被存在jar中, 而不是直接发送到浏览器
// 由于jar可以被测试检测到,这使得所有的cookie测试变得非常容易
foreach (static::$jar as $cookie)
{
static::set($cookie);
}
}
/**
* Send a cookie from the cookie jar back to the browser.
* 从cookie jar中发送一个cookie到浏览器
* @param array $cookie
* @return void
*/
protected static function set($cookie)
{
// extract() 从数组中将变量导入到当前的符号表 ,将关联数组的键名当做变量名,键值当做变量值
extract($cookie);
// $minutes,$name, $value 等没有定义,应该是框架bug
// time() 返回当前Unix时间戳
$time = ($minutes !== 0) ? time() + ($minutes * 60) : 0;
// A cookie payload can't exceed 4096 bytes, so if the payload is greater
// than that, we'll raise an error to warn the developer since it could
// cause serious cookie-based session problems.
$value = static::sign($name, $value);
// strlen() 获取字符串长度
if (strlen($value) > 4000)
{
throw new \Exception("Payload too large for cookie.");
}
// setcookie() 设置Cookie
setcookie($name, $value, $time, $path, $domain, $secure);
}
/**
* Get the value of a cookie.
* 获取一个cookie的值
* <code>
* // Get the value of the "favorite" cookie
* // 获取值为favorite的cookie
* $favorite = Cookie::get('favorite');
*
* // Get the value of a cookie or return a default value
* // 获取一个cookie的值或返回一个默认的值
* $favorite = Cookie::get('framework', 'Laravel');
* </code>
*
* @param string $name
* @param mixed $default
* @return string
*/
public static function get($name, $default = null)
{
if (isset(static::$jar[$name])) return static::$jar[$name]['value'];
$value = array_get($_COOKIE, $name);
if ( ! is_null($value) and isset($value[40]) and $value[40] == '~')
{
// The hash signature and the cookie value are separated by a tilde
// character for convenience. To separate the hash and the contents
// we can simply expode on that character.
//
// By re-feeding the cookie value into the "sign" method we should
// be able to generate a hash that matches the one taken from the
// cookie. If they don't, the cookie value has been changed.
list($hash, $value) = explode('~', $value, 2);
if (static::hash($name, $value) === $hash)
{
return $value;
}
}
return value($default);
}
/**
* Set the value of a cookie.
* 设置一个cookie的值
* <code>
* // Set the value of the "favorite" cookie
* // 设置favorite cookie的值
* Cookie::put('favorite', 'Laravel');
*
* // Set the value of the "favorite" cookie for twenty minutes
* // 设置favorite的cookie值为20分钟
* Cookie::put('favorite', 'Laravel', 20);
* </code>
*
* @param string $name
* @param string $value
* @param int $minutes
* @param string $path
* @param string $domain
* @param bool $secure
* @return void
*/
public static function put($name, $value, $minutes = 0, $path = '/', $domain = null, $secure = false)
{
// compact() 创建一个数组,包括变量名和它们的值
static::$jar[$name] = compact('name', 'value', 'minutes', 'path', 'domain', 'secure');
}
/**
* Set a "permanent" cookie. The cookie will last for one year.
* 设置一个永久的cookie。这个cookie将持续一年
* <code>
* // Set a cookie that should last one year
* Cookie::forever('favorite', 'Blue');
* </code>
*
* @param string $name
* @param string $value
* @param string $path
* @param string $domain
* @param bool $secure
* @return bool
*/
public static function forever($name, $value, $path = '/', $domain = null, $secure = false)
{
return static::put($name, $value, 525600, $path, $domain, $secure);
}
/**
* Generate a cookie signature based on the contents.
* 基于内容生成一个cookie签名
* @param string $name
* @param string $value
* @return string
*/
public static function sign($name, $value)
{
return static::hash($name, $value).'~'.$value;
}
/**
* Generate a cookie hash based on the contents.
* 基于内容生成一个cookie哈希值
* @param string $name
* @param string $value
* @return string
*/
protected static function hash($name, $value)
{
// sha1() 计算字符串的 sha1 散列值
return sha1($name.$value.Config::get('application.key'));
}
/**
* Delete a cookie.
* 删除一个cookie
* @param string $name
* @param string $path
* @param string $domain
* @param bool $secure
* @return bool
*/
public static function forget($name, $path = '/', $domain = null, $secure = false)
{
// 将值置空
return static::put($name, null, -2000, $path, $domain, $secure);
}
}