README

这是一个简单的客户端会话状态PHP实现，用于将会话数据嵌入到您的网页HTML内容中。

安装

只需运行 composer require perlucas/clientsessionstate

基础和基本用法

这是多种实现客户端会话状态模式之一。基本上，它通过将数据作为URL参数发送或将其隐藏在表单中来在客户端存储会话状态；然后在服务器端恢复它以使用。在这里您可以查看客户端会话状态和服务器会话状态的比较。使用此助手在您的HTML标记中存储非敏感数据，释放服务器上的内存使用。通常，您首先通过需要ClientSession的一个实例，并通过调用setEncodingKey方法来设置您的加密密钥。之后，您就可以开始向会话对象添加、检索和删除值。请注意，它以键值对格式工作。

<?php
use ClientSessionState\ClientSession;

$session = ClientSession::instance();
$session->setEncodingKey('This is my key'); // set key
$session->set('a_number', 22.5);
$session->set('an_array', array(11, 22, 33, 44));
$session->set('a_string', 'This is my session phrase');
$session->set('an_object', new stdClass());
$session->get('a_number'); // 22.5
$session->get('an_array'); // [11, 22, 33, 44]
$session->has('a_number'); // true
$session->has('an_unknown_value'); // false
$session->remove('a_number');
$session->has('a_number'); // false

输出会话

在处理会话对象之后，您可能需要将数据输出以在HTML标记中隐藏它。您应该看到的是会话对象的序列化加密版本，这是一个长字符串。我们将这个字符串称为会话字符串表示或简称会话字符串。您可以通过调用output外观来获取会话字符串

. . .
echo "Session string: " . $session->output()->string();
. . .

您可以在构建网站链接时将会话字符串作为URL参数发送

<a href="./myPage?session=<?=$session->output()->string()?>">
	My Link
</a>

另一方面，您可能能够将其包含在表单中，比如在隐藏输入中

<form action='./myPage.php'>
	. . .
	<?=$session->output()->input()?>
	. . .
</form>

使用不带参数的input方法将自动填充名为"session_data"的隐藏输入，其中包含会话字符串表示。您可以通过传递属性/值数组来覆盖输入属性

<form action='./myPage.php'>
	. . .
	<?=$session->output()->input([
		'name' => 'my_session',
		'type' => 'text',
		'readonly' => true
	])?>
	. . .
</form>

添加自定义输出

您可以添加自己的格式化程序来输出会话字符串表示。首先，您必须通过定义一个具有format方法的类来实现ClientSessionState\Contracts\SessionDataFormatter接口

. . .
class CustomFormatter implements SessionDataFormatter
{
	. . .
	public function format(string $input, ...$args) {
		// code here...
	}
}

$input参数是会话字符串表示。请注意，格式方法可能带有更多参数。代表您在格式方法中支持的参数的$args数组。这些参数在您从输出外观调用方法时传递

. . .
$session->output()->custom($arg1, $arg2);
/* Here you should implement the format method 
* for supporting 2 arguments to be passed in to
* the method call along with the $input param
*/
. . .

在定义了新的格式化程序之后，您必须将其注册才能使用它

. . .
$session->setFormatter('custom', new CustomFormatter);
. . .
// calling the formatter
$value = $session->output()->custom();
. . .
// calling the formatter with arguments
$value = $session->output()->custom($myFirstArg, $mySecondArg);

恢复会话

在将会话字符串嵌入到您的HTML中之后，您应该为您的后端准备接收$_GET或$_POST数组中的字符串。load方法将从会话字符串恢复您的会话对象。只需确保您正在使用在编码会话值时设置的相同密钥即可

$session = ClientSession::instance();
$session->setEncodingKey('This is my key');
$session->load($_GET['session']);
// You can use the session values here

JavaScript SDK

您可能希望在客户端操作DOM而不丢失会话字符串。JavaScript SDK为您提供获取会话字符串并将其嵌入到表单中的支持。首先，您必须通过调用js格式器来包含定义JS SDK的script标签

. . .
// <script> tags with the sdk definition
echo $session->output()->js();
. . .

现在，在客户端，您可以使用js外观。它由一个名为ClientSession的对象组成，该对象包含2个方法

• toString 返回会话字符串。您可以传递一个prepend和一个append字符串，以便在会话字符串前后返回。

console.log(ClientSession.toString());
console.log(ClientSession.toString("before session string "));
console.log(ClientSession.toString(null, " after session string"));

• addToForm 将一个名为"session"的隐藏输入添加到表单中。您应该传递表单元素或其ID值。可选地，您还可以传递一个包含要覆盖的输入属性的对象。

. . .
ClientSession.addToForm(document.getElementById(formId));
. . .
ClientSession.addToForm(formId);
. . .
ClientSession.addToForm(formId, {
	name: 'session_data'
});

会话对象上的js格式化程序可以接受一个参数，即js外观类名。如果您需要，可以使用它来定义一个更方便的类名。

. . .
echo $session->output()->js('SessionClass');
. . .
// then, on the client side, writing some javascript...
SessionClass.addToForm(formId);

扩展ClientSession类

会话外观作为ClientSessionState\ClientSession实例存在。您可能希望扩展此类以支持其他加密或序列化方法。ClientSession类定义了一些模板方法，允许您轻松扩展功能和支持其他用于加密和序列化数据的方

• createEncrypter方法是在ClientSession类上实现的工厂方法，必须返回一个用作加密引擎的ClientSessionState\Contracts\Encrypter实例。
• createSerializer方法必须返回一个用作序列化类的ClientSessionState\Contracts\Serializer实例。请注意，序列化类必须序列化和反序列化一个数组。这是因为会话数据是使用该数据结构持有的。
• setUpFormatters方法注册了input, string 和 js格式化程序。它可以扩展以在创建ClientSession实例时注册其他格式化程序。

示例

您可以在示例文件夹中看到一个完整的页面到页面导航，在客户端HTML中保持会话数据。此外，您可以在服务器上加载它并运行它以查看其工作原理。