README

icanboogie/session 包提供了一种轻松管理 PHP 会话的接口。您可以使用所需的选项创建会话实例，并在读取或写入时自动启动会话。会话实例用作数组，就像 $_SESSION。您可以为组件提供 会话段，以便它们有一个安全的地方来存储它们自己的会话值。可以在会话及其段中使用闪存值。最后，您可以使用 会话令牌 与不安全的 HTTP 方法一起使用，以防止 CSRF。

重要的是要注意，会话实例基本上是映射 $_SESSION 数组和 session_* 函数，因此您不需要更改应用程序设置中的任何内容。您可以使用 Redis 存储会话以及一些花哨的会话处理程序，这没有区别。

以下代码演示了会话实例的一些用法

<?php

use ICanBoogie\Session;

$session = new Session;

#
# The session is automatically started when reading or writing
#
if (!isset($session['bar']))
{
    $session['bar'] = 'foo';
}

#
# Optionally, changes can be commited right away,
# also closing the session.
#
$session->commit();

#
# The session is automatically re-started on read or write
#
$session['baz'] = 'dib';

#
# Using isolated session segments
#
$segment = $session->segments['Vendor\NameSpace'];
$segment['bar'] = 123;
echo $session->segments['Vendor\NameSpace']['bar']; // 123
$session->segments['Vendor\NameSpace']['bar'] = 456;
echo $segment['bar']; // 456

#
# Using flash
#
$session->flash['info'] = "Well done!";
$session->segments['Vendor\NameSpace']->flash['bar'] = 123;

#
# The session token can be used to prevent CSRF. A new token is
# generated if none exists.
#
$token = $session->token;       // 86eac2e0d91521df1efe7422e0d9ce48ef5ac75778ca36176bf4b84db9ff35858e491923e6f034ece8bcc4b38c3f7e99
$session->verify_token($token); // true

#
# Of course all of this is just mapping to the `$_SESSION` array
#
echo $_SESSION['bar']; // foo
echo $_SESSION['baz']; // dib
echo $_SESSION['Vendor\NameSpace']['bar']; // 456

入门

Session 实例是 PHP 会话的表示。它使用映射到 session_* 函数的参数创建。可以定义选项来自定义会话，它们的默认值是从 PHP 配置继承的。

以下代码演示了如何使用默认值实例化会话

use ICanBoogie\Session;

$session = new Session;

注意：没有任何东西阻止您使用多个 Session 实例，但并不推荐。

以下代码演示了如何使用选项来自定义会话实例。这里只演示了几个选项，更多选项可供选择。

use ICanBoogie\Session;
use ICanBoogie\Session\CookieParams;

$session = new Session([

    Session::OPTION_NAME => 'SID',
    Session::OPTION_CACHE_LIMITER => 'public',
    Session::OPTION_COOKIE_PARAMS => [

        CookieParams::OPTION_DOMAIN => '.mydomain.tld',
        CookieParams::OPTION_SECURE => true

    ]

]);

如果您在配置文件中定义这些选项，您可能希望使用轻量级的 SessionOptions 接口

<?php

// config/session.php

use ICanBoogie\SessionOptions as Session;

return [

    Session::OPTION_NAME => 'SID',
    Session::OPTION_CACHE_LIMITER => 'public',
    Session::OPTION_COOKIE_PARAMS => [

        CookieParams::OPTION_DOMAIN => '.mydomain.tld',
        CookieParams::OPTION_SECURE => true

    ]

];

会话段

会话段为组件提供了一个安全的地方来存储它们的值，而不会发生冲突。也就是说，两个组件可以安全地使用同一个键，因为它们的值存储在不同的会话 段 中。段作为会话值的命名空间。因此，选择一个安全的命名空间非常重要，类名通常是最佳选择。

会话和会话段实例都实现了 SessionSegment 接口。需要会话存储的组件应使用该接口而不是 Session 类。

注意：获取段不会启动会话，只有读取/写入才会自动启动会话。所以不要犹豫去获取会话段。

以下示例演示了如何将会话段注入到控制器中

<?php

use ICanBoogie\SessionSegment;

class UserController
{
    /**
     * @var SessionSegment
     */
    private $session;

    public function __construct(SessionSegment $session)
    {
        $this->session = $session;
    }

    public function action_post_login()
    {
        // …

        $this->session['user_id'] = $user->id;
    }
}

// …

use ICanBoogie\Session;

$session = new Session;
$controller = new UserController($session->segments[UserControlller::class]);

闪存值

闪存值是会话值，在读取后会被遗忘，尽管它们可以在 PHP 脚本的运行期间被读取多次。它们可以在会话或其段中设置。

以下示例演示了闪存值如何与会话和段一起工作

<?php

use ICanBoogie\Session;

$session = new Session;
$session->flash['abc'] = 123;
$session->segments['segment-one']->flash['abc'] = 456;

$_SESSION 数组看起来像这样

array(2) {
  '__FLASH__' =>
  array(1) {
    'abc' =>
    int(123)
  }
  'segment-one' =>
  array(1) {
    '__FLASH__' =>
    array(1) {
      'abc' =>
      int(456)
    }
  }
}

在读取闪存值后，它会从会话/段中消失，尽管它可以在 PHP 脚本的运行期间被读取多次

<?php

$session_abc = $session->flash['abc'];   // 123
$session_abc === $session->flash['abc']; // true
$segment_abc = $session->segments['segment-one']->flash['abc'];   // 456
$segment_abc === $session->segments['segment-one']->flash['abc']; // true

array(2) {
  '__FLASH__' =>
  array(0) {
  }
  'segment-one' =>
  array(1) {
    '__FLASH__' =>
    array(0) {
    }
  }
}

击败跨站请求伪造

会话实例提供了一个会话令牌，可以用来保护您的应用程序免受跨站请求伪造攻击。在处理使用HTTP方法POST、PUT和DELETE的不安全请求之前，您的应用程序应验证该令牌。

注意：您可以信赖会话始终有一个令牌。如果请求令牌时没有令牌，则创建一个新的令牌。

以下示例演示了如何使用会话令牌与POST表单一起使用

<?php

/**
  * @var \ICanBoogie\Session $session
  */

?>

<form method="POST" action="/articles">
    <input type="hidden" value="<?= $session->token ?>" name="_session_token" />
    <!-- the remainder of the form … -->
</form>

处理不安全请求时，请确保会话令牌有效

<?php

/**
  * @var \ICanBoogie\Session $session
  */

if (in_array($_SERVER['REQUEST_METHOD'], [ 'POST', 'PUT', 'DELETE' ]))
{
    $token = isset($_POST['_session_token']) ? $_POST['_session_token'] : null;

    if ($session->verify_token($token))
    {
        // Token is verified, we can proceed with the request.
    }
    else
    {
        // Token verification failed, we should throw an exception.
    }
}

安装

composer require icanboogie/session

文档

该软件包作为ICanBoogie框架文档的一部分进行说明。make doc命令可以生成软件包及其依赖项的文档。文档生成在build/docs目录下。需要ApiGen。可以使用make clean命令清理该目录。

测试

运行make test-container以创建并登录测试容器，然后运行make test以运行测试套件。或者，运行make test-coverage以带有测试覆盖率运行测试套件。打开build/coverage/index.html以查看代码覆盖率分析。

许可协议

icanboogie/session遵循新BSD许可协议发布。