README

翻译: 西班牙语

用于处理会话的PHP库。

• 要求
• 安装
• 可用的类
  • 会话类
  • 会话外观
• 使用的异常
• 用法
• 测试
• 待办事项
• 变更日志
• 贡献
• 赞助商
• 许可

要求

• 操作系统：Linux | Windows。

• PHP版本：8.0 | 8.1 | 8.2 | 8.3。

安装

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

要安装PHP Session库，只需

composer require josantonius/session

前面的命令只会安装必要的文件，如果您希望下载整个源代码，可以使用

composer require josantonius/session --prefer-source

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

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

可用的类

会话类

Josantonius\Session\Session

启动会话

/**
 * @throws HeadersSentException        if headers already sent.
 * @throws SessionStartedException     if session already started.
 * @throws WrongSessionOptionException if setting options failed.
 * 
 * @see https://php.ac.cn/session.configuration for List of available $options.
 */
public function start(array $options = []): bool;

检查会话是否已启动

public function isStarted(): bool;

通过名称设置属性

/**
 * @throws SessionNotStartedException if session was not started.
 */
public function set(string $name, mixed $value): void;

通过名称获取属性

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

获取所有属性

public function all(): array;

检查会话中是否存在属性

public function has(string $name): bool;

一次设置多个属性

/**
 * If attributes exist they are replaced, if they do not exist they are created.
 * 
 * @throws SessionNotStartedException if session was not started.
 */
public function replace(array $data): void;

通过名称删除属性并返回其值

/**
 * Optionally defines a default value when the attribute does not exist.
 * 
 * @throws SessionNotStartedException if session was not started.
 */
public function pull(string $name, mixed $default = null): mixed;

通过名称删除属性

/**
 * @throws SessionNotStartedException if session was not started.
 */
public function remove(string $name): void;

释放所有会话变量

/**
 * @throws SessionNotStartedException if session was not started.
 */
public function clear(): void;

获取会话ID

public function getId(): string;

设置会话ID

/**
 * @throws SessionStartedException if session already started.
 */
public function setId(string $sessionId): void;

使用新生成的ID更新当前会话ID

/**
 * @throws SessionNotStartedException if session was not started.
 */
public function regenerateId(bool $deleteOldSession = false): bool;

获取会话名称

public function getName(): string;

设置会话名称

/**
 * @throws SessionStartedException if session already started.
 */
public function setName(string $name): void;

销毁会话

/**
 * @throws SessionNotStartedException if session was not started.
 */
public function destroy(): bool;

会话外观

Josantonius\Session\Facades\Session

启动会话

/**
 * @throws HeadersSentException        if headers already sent.
 * @throws SessionStartedException     if session already started.
 * @throws WrongSessionOptionException if setting options failed.
 * 
 * @see https://php.ac.cn/session.configuration for List of available $options.
 */
public static function start(array $options = []): bool;

检查会话是否已启动

public static function isStarted(): bool;

通过名称设置属性

/**
 * @throws SessionNotStartedException if session was not started.
 */
public static function set(string $name, mixed $value): void;

通过名称获取属性

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

获取所有属性

public static function all(): array;

检查会话中是否存在属性

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

一次设置多个属性

/**
 * If attributes exist they are replaced, if they do not exist they are created.
 * 
 * @throws SessionNotStartedException if session was not started.
 */
public static function replace(array $data): void;

通过名称删除属性并返回其值

/**
 * Optionally defines a default value when the attribute does not exist.
 * 
 * @throws SessionNotStartedException if session was not started.
 */
public static function pull(string $name, mixed $default = null): mixed;

通过名称删除属性

/**
 * @throws SessionNotStartedException if session was not started.
 */
public static function remove(string $name): void;

释放所有会话变量

/**
 * @throws SessionNotStartedException if session was not started.
 */
public static function clear(): void;

获取会话ID

public static function getId(): string;

设置会话ID

/**
 * @throws SessionStartedException if session already started.
 */
public static function setId(string $sessionId): void;

使用新生成的ID更新当前会话ID

/**
 * @throws SessionNotStartedException if session was not started.
 */
public static function regenerateId(bool $deleteOldSession = false): bool;

获取会话名称

public static function getName(): string;

设置会话名称

/**
 * @throws SessionStartedException if session already started.
 */
public static function setName(string $name): void;

销毁会话

/**
 * @throws SessionNotStartedException if session was not started.
 */
public static function destroy(): bool;

使用的异常

use Josantonius\Session\Exceptions\HeadersSentException;
use Josantonius\Session\Exceptions\SessionException;
use Josantonius\Session\Exceptions\SessionNotStartedException;
use Josantonius\Session\Exceptions\SessionStartedException;
use Josantonius\Session\Exceptions\WrongSessionOptionException;

用法

此库的用法示例

不设置选项启动会话

use Josantonius\Session\Session;

$session = new Session();

$session->start();

use Josantonius\Session\Facades\Session;

Session::start();

设置选项启动会话

use Josantonius\Session\Session;

$session = new Session();

$session->start([
    // 'cache_expire' => 180,
    // 'cache_limiter' => 'nocache',
    // 'cookie_domain' => '',
    'cookie_httponly' => true,
    'cookie_lifetime' => 8000,
    // 'cookie_path' => '/',
    'cookie_samesite' => 'Strict',
    'cookie_secure'   => true,
    // 'gc_divisor' => 100,
    // 'gc_maxlifetime' => 1440,
    // 'gc_probability' => true,
    // 'lazy_write' => true,
    // 'name' => 'PHPSESSID',
    // 'read_and_close' => false,
    // 'referer_check' => '',
    // 'save_handler' => 'files',
    // 'save_path' => '',
    // 'serialize_handler' => 'php',
    // 'sid_bits_per_character' => 4,
    // 'sid_length' => 32,
    // 'trans_sid_hosts' => $_SERVER['HTTP_HOST'],
    // 'trans_sid_tags' => 'a=href,area=href,frame=src,form=',
    // 'use_cookies' => true,
    // 'use_only_cookies' => true,
    // 'use_strict_mode' => false,
    // 'use_trans_sid' => false,
]);

use Josantonius\Session\Facades\Session;

Session::start([
    'cookie_httponly' => true,
]);

检查会话是否已启动

use Josantonius\Session\Session;

$session = new Session();

$session->isStarted();

use Josantonius\Session\Facades\Session;

Session::isStarted();

通过名称设置属性

use Josantonius\Session\Session;

$session = new Session();

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

use Josantonius\Session\Facades\Session;

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

通过名称获取属性，不设置默认值

use Josantonius\Session\Session;

$session = new Session();

$session->get('foo'); // null if attribute does not exist

use Josantonius\Session\Facades\Session;

Session::get('foo'); // null if attribute does not exist

通过名称获取属性，设置默认值

use Josantonius\Session\Session;

$session = new Session();

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

use Josantonius\Session\Facades\Session;

Session::get('foo', false); // false if attribute does not exist

获取所有属性

use Josantonius\Session\Session;

$session = new Session();

$session->all();

use Josantonius\Session\Facades\Session;

Session::all();

检查会话中是否存在属性

use Josantonius\Session\Session;

$session = new Session();

$session->has('foo');

use Josantonius\Session\Facades\Session;

Session::has('foo');

一次设置多个属性

use Josantonius\Session\Session;

$session = new Session();

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

use Josantonius\Session\Facades\Session;

Session::replace(['foo' => 'bar', 'bar' => 'foo']);

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

use Josantonius\Session\Session;

$session = new Session();

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

use Josantonius\Session\Facades\Session;

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

删除属性并返回其值或不存在时的自定义值

use Josantonius\Session\Session;

$session = new Session();

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

use Josantonius\Session\Facades\Session;

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

通过名称删除属性

use Josantonius\Session\Session;

$session = new Session();

$session->remove('foo');

use Josantonius\Session\Facades\Session;

Session::remove('foo');

释放所有会话变量

use Josantonius\Session\Session;

$session = new Session();

$session->clear();

use Josantonius\Session\Facades\Session;

Session::clear();

获取会话ID

use Josantonius\Session\Session;

$session = new Session();

$session->getId();

use Josantonius\Session\Facades\Session;

Session::getId();

设置会话ID

use Josantonius\Session\Session;

$session = new Session();

$session->setId('foo');

use Josantonius\Session\Facades\Session;

Session::setId('foo');

使用新生成的ID更新当前会话ID

use Josantonius\Session\Session;

$session = new Session();

$session->regenerateId();

use Josantonius\Session\Facades\Session;

Session::regenerateId();

使用新ID更新当前会话ID，删除旧会话

use Josantonius\Session\Session;

$session = new Session();

$session->regenerateId(true);

use Josantonius\Session\Facades\Session;

Session::regenerateId(true);

获取会话名称

use Josantonius\Session\Session;

$session = new Session();

$session->getName();

use Josantonius\Session\Facades\Session;

Session::getName();

设置会话名称

use Josantonius\Session\Session;

$session = new Session();

$session->setName('foo');

use Josantonius\Session\Facades\Session;

Session::setName('foo');

销毁会话

use Josantonius\Session\Session;

$session = new Session();

$session->destroy();

use Josantonius\Session\Facades\Session;

Session::destroy();

测试

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

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

cd php-session

composer install

使用PHPUnit运行单元测试

composer phpunit

使用PHPCS运行代码标准测试

composer phpcs

使用PHP Mess Detector测试来检测代码风格中的不一致性

composer phpmd

运行所有之前的测试

composer tests

待办事项

• 添加新功能
• 改进测试
• 改进文档
• 改进README文件中的英文翻译
• 重构代码以禁用代码风格规则（请参阅phpmd.xml和phpcs.xml）
• 展示如何更新会话生命周期
• 是否添加启用/禁用异常的功能？
• 是否添加在会话属性前添加前缀的功能？

变更日志

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

贡献

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

感谢所有贡献者！❤️

赞助商

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

许可

本存储库采用MIT许可证。

版权所有 © 2017-至今，Josantonius