README

简介

FireSessions 是一个用于管理项目会话的 PHP 库。它允许您将会话数据存储在本地磁盘、Memcached 服务器或 Redis 服务器上；该库可以管理 3 种类型的会话变量：用户数据、闪存数据和临时数据。通过其所有驱动，该库支持对打开的会话进行锁定。

安装

您可以通过 composer 安装 FireSessions。

composer require kattsoftware/firesessions:^1.1

配置

要开始使用此库，您必须进行设置，例如。

<?php

require_once 'vendor/autoload.php';

use FireSessions\Session;

$config = array(
    'driver' => Session::FILES_DRIVER,
    'cookie_name' => 'fsessions',
    'save_path' => __DIR__ . DIRECTORY_SEPARATOR . 'sessions',
    'expiration' => 7200,
    'regenerate_time' => 300,
    'destroy_on_regenerate' => false
);

$session = new Session($config);

如您所见，设置是一个关联数组；它们可能因驱动而异。以下是可以在使用任何驱动时设置的设置列表。

文件驱动

文件驱动将您的会话数据文件保存到服务器的磁盘上。此处剩余的唯一设置是 save_path。

save_path 是一个可写目录的绝对完整路径，PHP 进程可以将其会话文件放入其中。如果没有设置，FileSessions 将尝试使用 session_save_path() 函数返回的值。

Memcached 驱动

此驱动程序将所有会话数据保存到 Memcached 服务器实例。

在这里，save_path 是以逗号分隔的 server:port 对的列表。

$config['save_path'] = 'localhost:11211,192.168.1.1:11211';

您还可以添加第三个参数（:weight），它指定 Memcached 服务器优先级。

// 192.168.0.1:11211 has a higher priority (5), while 192.168.1.1:11211 has the weight 1.
$config['save_path'] = '192.168.0.1:11211:5,192.168.1.1:11211:1';

请注意，这可能会导致性能提升或降低；它可能取决于环境。如果您不确定，请不要设置服务器的权重。

默认情况下，Memcached 驱动程序将检索本地池服务器（Memcached::getServerList()）。要禁用此功能，您可以使用 fetch_pool_servers 设置。

$config['fetch_pool_servers'] = false;

Redis 驱动

Redis 驱动程序将您的会话数据保存到 Redis 服务器实例。

对于此驱动程序，save_path 设置是以逗号分隔的连接参数名称及其值的集合（param=value）。

$config['save_path'] = 'host=localhost,port=6379,password=myPassword,database=2,timeout=30,prefix=sessions:';

// host - (required) the hostname of Redis server
// port - (optional) the Redis server port
// password - (optional) Redis authentication password
// database - (optional) which Redis database to use
// timeout - (optional) Redis connection timeout, in seconds
// prefix - (optional) Prefix of the entries names (if not set, the "cookie_name" setting will be used)

使用

FireSession 实现了 3 种类型的会话变量：用户数据、闪存数据和临时数据。

用户数据

用户数据 代表在整个会话生命周期中设置的变量集合。您可以使用它们来存储登录用户的 ID、特定用户的权限等。简单来说，它们是经典的 $_SESSION 变量。

要设置 用户数据变量，您可以使用以下调用

$session->setUserdata('logged_userid', 1234);
$session->setUserdata('logged_username', 'myUsername');

// or

$session->logged_userid = 1234;
$session->logged_username = 'myUsername';

// you may also set the variable by assigning $_SESSION variable:

$_SESSION['logged_userid'] = 1234;
$_SESSION['logged_username'] = 'myUsername';

// you can also set multiple user data at once:
$session->setUserdata(array(
    'logged_userid' => 1234,
    'logged_username' => 'myUsername'
));

但是，这里的建议是使用 $session 变量（Session 实例），这样您将在整个项目中保持一致性。

要获取 用户数据变量，您可以使用以下调用

echo $session->userdata('logged_userid'); // outputs 1234
echo $session->userdata('logged_username'); // outputs myUsername

// or

echo $session->logged_userid; // outputs 1234
echo $session->logged_username; // outputs myUsername

// or you can use the $_SESSION variable:

echo $_SESSION['logged_userid']; // outputs 1234
echo $_SESSION['logged_username']; // outputs myUsername

再次，建议使用 Session 实例。 :)

如果请求的变量不存在，userdata() 将返回 null。

如果您需要 所有用户数据，您可以请求整个用户数据关联数组

var_dump($session->userdata()); // Outputs all user data

要 删除用户数据，您可以使用以下调用

// removes the "logged_userid" variable
$session->unsetUserdata('logged_userid');

// removes multiple user data
$session->unsetUserdata(array('logged_userid', 'logger_username'));

闪存数据

闪存数据与用户数据相同，但它们的生命周期是当前和下一个HTTP请求。之后，它们将被删除。

要设置闪存数据，可以使用以下调用

$session->setFlashdata('success_message', 'Your profile has been saved!');

// setting multiple flash data at once:

$session->setFlashdata(array(
    'firstname_validation' => 'Invalid first name!',
    'email_validation' => 'Invalid e-mail address!'
));

要获取闪存数据的值，可以使用以下调用

echo $session->flashdata('email_validation');
// outputs The typed e-mail address is invalid!

// you can also fetch the entire flash data as an associative array:
var_dump($session->flashdata());

如果您在重定向到下一个请求后想为另一个请求保留闪存数据，可以使用以下调用

$session->keepFlashdata('email_validation');
// Preserves the "email_validation" flash for another request as well

// Preserve more than one flash data for another request
$session->keepFlashdata(array('email_validation', 'firstname_validation'));

要删除闪存数据，可以使用以下调用

// removes the "email_validation" flash data
$session->unsetFlashdata('email_validation');

// removes multiple flash data
$session->unsetUserdata(array('email_validation', 'firstname_validation'));

临时数据

临时数据类似于闪存数据，但它们的存活时间是一个指定的秒数，而不是当前和下一个请求。

要设置临时数据，可以使用以下调用

// this will create a temp data 'quiz_score', having the value of 72
// and expiring after 300 seconds
$session->setTempdata('quiz_score', 73, 300);

// setting multiple temp data at once
$session->setTempdata(array(
    'quiz_question1' => 10,
    'quiz_question2' => 0
), array(
    'quiz_question1' => 300, // quiz_question1 will expire after 300 seconds
    'quiz_question2' => 350 // quiz_question2 will expire after 350 seconds
));

// or you can use the same expiration time for all items:

$session->setTempdata(array(
    'quiz_question1' => 10,
    'quiz_question2' => 0
), 300);

要获取临时数据的值，可以使用以下调用

echo $session->tempdata('quiz_question1');
// outputs 10

// you can also fetch the entire temp data as an associative array:
var_dump($session->tempdata());

要删除临时数据，可以使用以下调用

// removes the 'quiz_question1' temp data
$session->unsetTempdata('quiz_question1');

// or you may set multiple temp data at once:

$session->unsetTempdata('quiz_question1', 'quiz_question2');

您还可以检查某些变量是否存在

// all of the below calls return a boolean value
$session->hasUserdata('logged_userid'); 
$session->hasFlashdata('email_validation');
$session->hasTempdata('quizz_answers');

如果您想销毁整个会话（这意味着所有类型的变量），可以使用以下调用

// Deletes the user, flash and temp data + the session cookie
$session->destroy();

使用SessionFactory

如果出于任何原因，您将在项目的不同地方需要这个库，您将需要多次使用Session实例。在这种情况下，new Session($config)将不起作用，因为库已经被创建。

在这种情况下，您可以在所有地方使用SessionFactory，这样您将始终得到第一个实例

<?php

use FireSessions\SessionFactory;

// here goes your config
// $config = array(...);

// A global instance is created
$session = SessionFactory::getInstance($config);

// ... in another place/file, you may get the already created instance again:

$session = SessionFactory::getInstance();

定义自定义驱动程序

您也可以创建自己的会话驱动程序！在这种情况下，您将使用FireSessions\DriversFactory工厂。

为此，您需要构建一个扩展FireSessions\BaseSessionDriver类的类（这个类本质上实现了SessionHandlerInterface）。除了实现SessionHandlerInterface的方法外，您还必须实现额外的acquireLock和releaseLock抽象方法。

不要忘记您的自定义驱动程序也需要接收$config数组。

之后，请按如下方式调用父构造函数

parent::__construct($config);

一旦您做到了这一点，您就可以使用已经可用的方法，例如BaseSessionDriver::destroyCookie()和BaseSessionDriver::getIp()。

要使自定义驱动程序可供使用，在使用Session客户端之前使用以下调用

DriversFactory::registerDriver('myDriver', MyDriver::class);

// or you can send the already created custom driver instance:
// $myDriver = new MyDriver(...);
DriversFactory::registerDriver('myDriver', $myDriver);

如果您作为第二个参数提供类名（而不是自定义驱动程序的实际实例），则工厂将尝试通过提供$config作为参数来创建实例。

现在您可以使用您自定义的驱动程序了！

$config = array(
    'driver' => 'myDriver',
    ...
);

$session = new Session($config);

致谢

此库紧密遵循CodeIgniter 3会话库的实现和API。向他们的成员和贡献者表示衷心的感谢！

许可证

此库根据MIT许可证（MIT）许可。有关更多信息，请参阅LICENSE文件。

版权（c）2017 KattSoftware 开发团队。