README

翻译: 西班牙语

PHP库，用于处理cookie。

• 需求
• 安装
• 可用类
  • Cookie类
  • Cookie外观
• 使用的异常
• 用法
• 关于Cookie过期
• 测试
• 待办事项
• 变更日志
• 贡献
• 赞助
• 许可证

需求

• 操作系统: Linux。

• PHP版本: 8.1 | 8.2 | 8.3。

安装

安装此扩展的首选方式是通过Composer。

要安装PHP Cookie库，只需

composer require josantonius/cookie

上述命令只会安装必要的文件，如果您想下载整个源代码，可以使用

composer require josantonius/cookie --prefer-source

您也可以使用Git 克隆整个仓库

git clone https://github.com/josantonius/php-cookie.git

可用类

Cookie类

Josantonius\Cookie\Cookie

设置cookie选项

/**
 * Cookie options:
 * 
 * domain:   Domain for which the cookie is available.
 * expires:  The time the cookie will expire.
 * httpOnly: If cookie will only be available through the HTTP protocol.
 * path:     Path for which the cookie is available.
 * raw:      If cookie will be sent as a raw string.
 * sameSite: Enforces the use of a Lax or Strict SameSite policy.
 * secure:   If cookie will only be available through the HTTPS protocol.
 * 
 * These settings will be used to create and delete cookies.
 * 
 * @throws CookieException if $sameSite value is wrong.
 *
 * @see https://php.ac.cn/manual/en/datetime.formats.php for date formats.
 * @see https://php.ac.cn/manual/en/function.setcookie.php for more information.
 */
public function __construct(
    private string              $domain   = '',
    private int|string|DateTime $expires  = 0,
    private bool                $httpOnly = false,
    private string              $path     = '/',
    private bool                $raw      = false,
    private null|string         $sameSite = null,
    private bool                $secure   = false
);

通过名称设置cookie

/**
 * @throws CookieException if headers already sent.
 * @throws CookieException if failure in date/time string analysis.
 */
public function set(
    string $name,
    mixed $value,
    null|int|string|DateTime $expires = null
): void;

一次性设置多个cookie

/**
 * If cookies exist they are replaced, if they do not exist they are created.
 *
 * @throws CookieException if headers already sent.
 */
public function replace(
    array $data,
    null|int|string|DateTime $expires = null
): void;

通过名称获取cookie

/**
 * Optionally defines a default value when the cookie does not exist.
 */
public function get(string $name, mixed $default = null): mixed;

获取所有cookie

public function all(): array;

检查cookie是否存在

public function has(string $name): bool;

通过名称删除cookie并返回其值

/**
 * Optionally defines a default value when the cookie does not exist.
 * 
 * @throws CookieException if headers already sent.
 */
public function pull(string $name, mixed $default = null): mixed;

通过名称删除cookie

/**
 * @throws CookieException if headers already sent.
 * @throws CookieException if failure in date/time string analysis.
 */
public function remove(string $name): void;

Cookie外观

Josantonius\Cookie\Facades\Cookie

设置cookie选项

/**
 * Cookie options:
 * 
 * domain:   Domain for which the cookie is available.
 * expires:  The time the cookie will expire.
 * httpOnly: If cookie will only be available through the HTTP protocol.
 * path:     Path for which the cookie is available.
 * raw:      If cookie will be sent as a raw string.
 * sameSite: Enforces the use of a Lax or Strict SameSite policy.
 * secure:   If cookie will only be available through the HTTPS protocol.
 * 
 * These settings will be used to create and delete cookies.
 * 
 * @throws CookieException if $sameSite value is wrong.
 *
 * @see https://php.ac.cn/manual/en/datetime.formats.php for date formats.
 * @see https://php.ac.cn/manual/en/function.setcookie.php for more information.
 */
public static function options(
    string              $domain   = '',
    int|string|DateTime $expires  = 0,
    bool                $httpOnly = false,
    string              $path     = '/',
    bool                $raw      = false,
    null|string         $sameSite = null,
    bool                $secure   = false
): void;

通过名称设置cookie

/**
 * @throws CookieException if headers already sent.
 * @throws CookieException if failure in date/time string analysis.
 */
public static function set(
    string $name,
    mixed $value,
    null|int|string|DateTime $expires = null
): void;

一次性设置多个cookie

/**
 * If cookies exist they are replaced, if they do not exist they are created.
 *
 * @throws CookieException if headers already sent.
 */
public static function replace(
    array $data,
    null|int|string|DateTime $expires = null
): void;

通过名称获取cookie

/**
 * Optionally defines a default value when the cookie does not exist.
 */
public static function get(string $name, mixed $default = null): mixed;

获取所有cookie

public static function all(): array;

检查cookie是否存在

public static function has(string $name): bool;

通过名称删除cookie并返回其值

/**
 * Optionally defines a default value when the cookie does not exist.
 * 
 * @throws CookieException if headers already sent.
 */
public static function pull(string $name, mixed $default = null): mixed;

通过名称删除cookie

/**
 * @throws CookieException if headers already sent.
 * @throws CookieException if failure in date/time string analysis.
 */
public static function remove(string $name): void;

使用的异常

use Josantonius\Cookie\Exceptions\CookieException;

用法

此库的使用示例

使用默认选项创建Cookie实例

use Josantonius\Cookie\Cookie;

$cookie = new Cookie();

use Josantonius\Cookie\Facades\Cookie;

Cookie::options();

使用自定义选项创建Cookie实例

use Josantonius\Cookie\Cookie;

$cookie = new Cookie(
    domain: 'example.com',
    expires: time() + 3600,
    httpOnly: true,
    path: '/foo',
    raw: true,
    sameSite: 'Strict',
    secure: true,
);

use Josantonius\Cookie\Facades\Cookie;

Cookie::options(
    expires: 'now +1 hour',
    httpOnly: true,
);

通过名称设置cookie

use Josantonius\Cookie\Cookie;

$cookie = new Cookie();

$cookie->set('foo', 'bar');

use Josantonius\Cookie\Facades\Cookie;

Cookie::set('foo', 'bar');

通过修改过期时间设置名称为cookie

use Josantonius\Cookie\Cookie;

$cookie = new Cookie();

$cookie->set('foo', 'bar', time() + 3600);

use Josantonius\Cookie\Facades\Cookie;

Cookie::set('foo', 'bar', new DateTime('now +1 hour'));

一次性设置多个cookie

use Josantonius\Cookie\Cookie;

$cookie = new Cookie();

$cookie->replace([
    'foo' => 'bar',
    'bar' => 'foo'
]);

use Josantonius\Cookie\Facades\Cookie;

Cookie::replace([
    'foo' => 'bar',
    'bar' => 'foo'
], time() + 3600);

通过修改过期时间一次性设置多个cookie

use Josantonius\Cookie\Cookie;

$cookie = new Cookie();

$cookie->replace([
    'foo' => 'bar',
    'bar' => 'foo'
], time() + 3600);

use Josantonius\Cookie\Facades\Cookie;

Cookie::replace([
    'foo' => 'bar',
    'bar' => 'foo'
], time() + 3600);

通过名称获取cookie

use Josantonius\Cookie\Cookie;

$cookie = new Cookie();

$cookie->get('foo'); // null if the cookie does not exist

use Josantonius\Cookie\Facades\Cookie;

Cookie::get('foo'); // null if the cookie does not exist

如果cookie不存在，则通过名称获取默认值

use Josantonius\Cookie\Cookie;

$cookie = new Cookie();

$cookie->get('foo', false); // false if cookie does not exist

use Josantonius\Cookie\Facades\Cookie;

Cookie::get('foo', false); // false if cookie does not exist

获取所有cookie

use Josantonius\Cookie\Cookie;

$cookie = new Cookie();

$cookie->all();

use Josantonius\Cookie\Facades\Cookie;

Cookie::all();

检查cookie是否存在

use Josantonius\Cookie\Cookie;

$cookie = new Cookie();

$cookie->has('foo');

use Josantonius\Cookie\Facades\Cookie;

Cookie::has('foo');

通过名称删除cookie并返回其值

use Josantonius\Cookie\Cookie;

$cookie = new Cookie();

$cookie->pull('foo'); // null if attribute does not exist

use Josantonius\Cookie\Facades\Cookie;

Cookie::pull('foo'); // null if attribute does not exist

删除cookie并返回其值或不存在时的默认值

use Josantonius\Cookie\Cookie;

$cookie = new Cookie();

$cookie->pull('foo', false); // false if attribute does not exist

use Josantonius\Cookie\Facades\Cookie;

Cookie::pull('foo', false); // false if attribute does not exist

通过名称删除cookie

use Josantonius\Cookie\Cookie;

$cookie = new Cookie();

$cookie->remove('foo');

use Josantonius\Cookie\Facades\Cookie;

Cookie::remove('foo');

关于cookie过期

• 此库的几个方法中使用的expires参数接受以下类型：int|string|DateTime。

  • 整数将被处理为除了零之外的Unix时间。

  • 字符串将被处理为日期/时间格式。有关更多信息，请参阅支持的日期和时间格式。

    $cookie = new Cookie(
        expires: '2016-12-15 +1 day'
    );

    它将与以下类似

    $cookie = new Cookie(
        expires: new DateTime('2016-12-15 +1 day')
    );

  • DateTime对象将被用来获取Unix时间。

• 如果expires参数用于set或replace方法，它将取代cookie选项中设置的expires值。

  $cookie = new Cookie(
      expires: 'now +1 minute'
  );
  
  $cookie->set('foo', 'bar');                        // Expires in 1 minute
  
  $cookie->set('bar', 'foo', 'now +8 days');         // Expires in 8 days
  
  $cookie->replace(['foo' => 'bar']);                // Expires in 1 minute
  
  $cookie->replace(['foo' => 'bar'], time() + 3600); // Expires in 1 hour

• 如果传递给选项的expires参数是一个日期/时间字符串，它将在使用set或replace方法时进行格式化，而不是在设置选项时。

  $cookie = new Cookie(
      expires: 'now +1 minute', // It will not be formatted as unix time yet
  );
  
  $cookie->set('foo', 'bar');   // It is will formatted now and expires in 1 minute

测试

要运行测试，您只需要composer并执行以下操作

git clone https://github.com/josantonius/php-cookie.git

cd php-cookie

composer install

使用PHPUnit运行单元测试

composer phpunit

使用PHPCS运行代码标准测试

composer phpcs

运行PHP Mess Detector测试以检测代码样式的不一致性

composer phpmd

运行所有之前的测试

composer tests

待办事项

• 添加新功能
• 改进测试
• 改进文档
• 改进README文件中的英文翻译
• 重构代码以禁用代码样式规则（请参阅phpmd.xml和phpcs.xml）

变更日志

每个版本的详细更改记录在发行说明中。

贡献

在发起拉取请求、开始讨论或报告问题之前，请务必阅读贡献指南。

感谢所有贡献者！❤️

赞助

如果这个项目帮助您减少了开发时间，您可以通过赞助我来支持我的开源工作 😊

许可证

本仓库遵循MIT许可证。

版权所有 © 2016-至今，Josantonius