mirror of
https://github.com/php/doc-zh.git
synced 2026-03-24 15:12:20 +01:00
8c2ec3127d
* Update book.xml * Update constants.xml * Update examples.xml * Update security.xml * Update upload-progress.xml * Update session-cache-expire.xml * Update session-cache-limiter.xml * Update session-destroy.xml * Update session-encode.xml * Update session-get-cookie-params.xml * Update session-id.xml * Update session-name.xml * Update session-regenerate-id.xml * Update session-save-path.xml * Update session-set-cookie-params.xml * Update session-set-save-handler.xml * Update session-start.xml * Update session-start.xml * Update session-status.xml * Update session-unset.xml * Update book.xml * Update session-cache-expire.xml * Update session-unset.xml
371 lines
14 KiB
XML
371 lines
14 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
||
<!-- $Revision$ -->
|
||
<!-- EN-Revision: 184f3f7bd45643cb80f828d0bb001991ec3a5fad Maintainer: yuanyuqiang Status: ready -->
|
||
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.session-set-save-handler" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||
<refnamediv>
|
||
<refname>session_set_save_handler</refname>
|
||
<refpurpose>设置用户自定义会话存储函数</refpurpose>
|
||
</refnamediv>
|
||
|
||
<refsect1 role="description">
|
||
&reftitle.description;
|
||
<methodsynopsis>
|
||
<type>bool</type><methodname>session_set_save_handler</methodname>
|
||
<methodparam><type>callable</type><parameter>open</parameter></methodparam>
|
||
<methodparam><type>callable</type><parameter>close</parameter></methodparam>
|
||
<methodparam><type>callable</type><parameter>read</parameter></methodparam>
|
||
<methodparam><type>callable</type><parameter>write</parameter></methodparam>
|
||
<methodparam><type>callable</type><parameter>destroy</parameter></methodparam>
|
||
<methodparam><type>callable</type><parameter>gc</parameter></methodparam>
|
||
<methodparam choice="opt"><type>callable</type><parameter>create_sid</parameter></methodparam>
|
||
<methodparam choice="opt"><type>callable</type><parameter>validate_sid</parameter></methodparam>
|
||
<methodparam choice="opt"><type>callable</type><parameter>update_timestamp</parameter></methodparam>
|
||
</methodsynopsis>
|
||
<para>
|
||
可以使用下面的方式来注册自定义会话存储函数：
|
||
</para>
|
||
<methodsynopsis>
|
||
<type>bool</type><methodname>session_set_save_handler</methodname>
|
||
<methodparam><type>object</type><parameter>sessionhandler</parameter></methodparam>
|
||
<methodparam choice="opt"><type>bool</type><parameter>register_shutdown</parameter><initializer>&true;</initializer></methodparam>
|
||
</methodsynopsis>
|
||
<para>
|
||
<function>session_set_save_handler</function> 设置用户自定义
|
||
会话存储函数。
|
||
如果想使用 PHP 内置的会话存储机制之外的方式，
|
||
可以使用本函数。
|
||
例如，可以自定义会话存储函数来将会话数据存储到数据库。
|
||
</para>
|
||
</refsect1>
|
||
|
||
<refsect1 role="parameters">
|
||
&reftitle.parameters;
|
||
<para>
|
||
本函数有 2 种原型：
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term><parameter>sessionhandler</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
实现了
|
||
<interfacename>SessionHandlerInterface</interfacename>，
|
||
<interfacename>SessionIdInterface</interfacename>（可选） 和/或
|
||
<interfacename>SessionUpdateTimestampHandlerInterface</interfacename>
|
||
接口的对象，
|
||
例如 <classname>SessionHandler</classname>。
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>register_shutdown</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
将函数 <function>session_write_close</function> 注册为
|
||
<function>register_shutdown_function</function> 函数。
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
或者
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term><parameter>open(string $savePath, string $sessionName)</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
实现了以下签名的 callable 回调：
|
||
<methodsynopsis>
|
||
<type>bool</type><methodname><replaceable>open</replaceable></methodname>
|
||
<methodparam><type>string</type><parameter>savePath</parameter></methodparam>
|
||
<methodparam><type>string</type><parameter>sessionName</parameter></methodparam>
|
||
</methodsynopsis>
|
||
</para>
|
||
<para>
|
||
open 回调函数类似于类的构造函数，
|
||
在会话打开的时候会被调用。
|
||
这是自动开始会话或者通过调用 <function>session_start</function> 手动开始会话
|
||
之后第一个被调用的回调函数。
|
||
此回调函数操作成功返回 &true;，反之返回 &false;。
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>close</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
close 回调函数类似于类的析构函数。
|
||
在 write 回调函数调用之后调用。
|
||
当调用 <function>session_write_close</function> 函数之后，也会调用 close 回调函数。
|
||
此回调函数操作成功返回 &true;，反之返回 &false;。
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>read</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
实现了以下签名的 callable 回调：
|
||
<methodsynopsis>
|
||
<type>string</type><methodname><replaceable>read</replaceable></methodname>
|
||
<methodparam><type>string</type><parameter>sessionId</parameter></methodparam>
|
||
</methodsynopsis>
|
||
</para>
|
||
<para>
|
||
如果会话中有数据，read 回调函数必须返回将会话数据编码（序列化）后的字符串。
|
||
如果会话中没有数据，read 回调函数返回空字符串。
|
||
</para>
|
||
<para>
|
||
在自动开始会话或者通过调用
|
||
<function>session_start</function> 函数手动开始会话之后，PHP 内部调用 read 回调函数来获取会话数据。
|
||
在调用 read 之前，PHP 会调用 open 回调函数。
|
||
</para>
|
||
<para>
|
||
read 回调返回的序列化之后的字符串格式必须与 <parameter>write</parameter> 回调函数保存数据时的格式完全一致。
|
||
PHP 会自动反序列化返回的字符串并填充 <varname>$_SESSION</varname> 超级全局变量。
|
||
虽然数据看起来和 <function>serialize</function> 函数很相似，
|
||
但是需要提醒的是，它们是不同的。
|
||
请参考： <link linkend="ini.session.serialize-handler">session.serialize_handler</link>。
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>write</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
实现了以下签名的 callable 回调：
|
||
<methodsynopsis>
|
||
<type>bool</type><methodname><replaceable>write</replaceable></methodname>
|
||
<methodparam><type>string</type><parameter>sessionId</parameter></methodparam>
|
||
<methodparam><type>string</type><parameter>data</parameter></methodparam>
|
||
</methodsynopsis>
|
||
</para>
|
||
<para>
|
||
在会话保存数据时会调用 <parameter>write</parameter> 回调函数。
|
||
此回调函数接收当前会话 ID 以及 <varname>$_SESSION</varname> 中数据序列化之后的字符串作为参数。
|
||
序列化会话数据的过程由 PHP 根据 <link linkend="ini.session.serialize-handler">session.serialize_handler</link> 设定值来完成。
|
||
</para>
|
||
<para>
|
||
序列化后的数据将和会话 ID 关联在一起进行保存。
|
||
当调用 <parameter>read</parameter> 回调函数获取数据时，所返回的数据必须要和
|
||
传入 <parameter>write</parameter> 回调函数的数据完全保持一致。
|
||
</para>
|
||
<para>
|
||
PHP 会在脚本执行完毕或调用 <function>session_write_close</function> 函数之后调用此回调函数。
|
||
注意，在调用完此回调函数之后，PHP 内部会调用 <parameter>close</parameter> 回调函数。
|
||
<note>
|
||
<para>
|
||
PHP 会在输出流写入完毕并且关闭之后
|
||
才调用 write 回调函数，
|
||
所以在 write 回调函数中的调试信息不会输出到浏览器中。
|
||
如果需要在 write 回调函数中使用调试输出，
|
||
建议将调试输出写入到文件。
|
||
</para>
|
||
</note>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>destroy</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
实现了以下签名的 callable 回调：
|
||
<methodsynopsis>
|
||
<type>bool</type><methodname><replaceable>destroy</replaceable></methodname>
|
||
<methodparam><type>string</type><parameter>sessionId</parameter></methodparam>
|
||
</methodsynopsis>
|
||
</para>
|
||
<para>
|
||
当调用 <function>session_destroy</function> 函数，
|
||
或者调用 <function>session_regenerate_id</function> 函数并且设置 destroy 参数为 &true; 时，
|
||
会调用此回调函数。此回调函数操作成功返回 &true;，反之返回 &false;。
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>gc</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
实现了以下签名的 callable 回调：
|
||
<methodsynopsis>
|
||
<type>bool</type><methodname><replaceable>gc</replaceable></methodname>
|
||
<methodparam><type>int</type><parameter>lifetime</parameter></methodparam>
|
||
</methodsynopsis>
|
||
</para>
|
||
<para>
|
||
为了清理会话中的旧数据，PHP 会不时的调用垃圾收集回调函数。
|
||
调用周期由 <link linkend="ini.session.gc-probability">session.gc_probability</link>
|
||
和 <link linkend="ini.session.gc-divisor">session.gc_divisor</link> 参数控制。
|
||
传入到此回调函数的 lifetime 参数由 <link linkend="ini.session.gc-maxlifetime">session.gc_maxlifetime</link> 设置。
|
||
此回调函数操作成功返回 &true;，反之返回 &false;。
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>create_sid</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
实现了以下签名的 callable 回调：
|
||
<methodsynopsis>
|
||
<type>string</type><methodname><replaceable>create_sid</replaceable></methodname>
|
||
<void/>
|
||
</methodsynopsis>
|
||
</para>
|
||
<para>
|
||
需要新的会话 ID 时，执行此回调函数。
|
||
它被调用时不会传入参数，其返回值应该是一个字符串格式的、有效的 session ID。
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>validate_sid</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
实现了以下签名的 callable 回调：
|
||
<methodsynopsis>
|
||
<type>bool</type><methodname><replaceable>validate_sid</replaceable></methodname>
|
||
<methodparam><type>string</type><parameter>key</parameter></methodparam>
|
||
</methodsynopsis>
|
||
</para>
|
||
<para>
|
||
开启 <link linkend="ini.session.use-strict-mode">session.use_strict_mode</link> 后，
|
||
当启动一个 session 时，提供了 session ID 后会执行此回调。
|
||
参数 <parameter>key</parameter> 是待验证的 session ID。
|
||
如果该 ID 的 session 已经存在，则为有效 session ID。
|
||
成功时返回值应当为 &true;，失败时为 &false;。
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>update_timestamp</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
实现了以下签名的 callable 回调：
|
||
<methodsynopsis>
|
||
<type>bool</type><methodname><replaceable>update_timestamp</replaceable></methodname>
|
||
<methodparam><type>string</type><parameter>key</parameter></methodparam>
|
||
<methodparam><type>string</type><parameter>val</parameter></methodparam>
|
||
</methodsynopsis>
|
||
</para>
|
||
<para>
|
||
更新 session 时执行此回调。
|
||
参数 <parameter>key</parameter> 是 session ID；参数 <parameter>val</parameter> 是 session 的数据。
|
||
成功时返回值应当为 &true;，失败时为 &false;。
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</para>
|
||
</refsect1>
|
||
|
||
<refsect1 role="returnvalues">
|
||
&reftitle.returnvalues;
|
||
<para>
|
||
&return.success;
|
||
</para>
|
||
</refsect1>
|
||
|
||
<refsect1 role="examples">
|
||
&reftitle.examples;
|
||
<para>
|
||
<example>
|
||
<title>
|
||
自定义会话处理程序：完整代码请参见 <classname>SessionHandlerInterface</classname>。
|
||
</title>
|
||
<para>
|
||
这里仅列出了调用方式，完整代码请参见 <classname>SessionHandlerInterface</classname>。
|
||
</para>
|
||
<para>
|
||
这里使用了 <function>session_set_save_handler</function> 函数的 OOP 原型
|
||
并且使用第二个参数来注册 shutdown 函数。
|
||
当将对象注册为会话保存处理程序时，建议使用这种方式。
|
||
</para>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<?php
|
||
class MySessionHandler implements SessionHandlerInterface
|
||
{
|
||
// 在这里实现接口
|
||
}
|
||
|
||
$handler = new MySessionHandler();
|
||
session_set_save_handler($handler, true);
|
||
session_start();
|
||
|
||
// 现在可以使用 $_SESSION 保存以及获取数据了
|
||
]]>
|
||
</programlisting>
|
||
</example>
|
||
</para>
|
||
</refsect1>
|
||
|
||
<refsect1 role="notes">
|
||
&reftitle.notes;
|
||
<warning>
|
||
<para>
|
||
在对象销毁之后才会调用
|
||
<parameter>write</parameter> 和 <parameter>close</parameter> 回调函数，
|
||
所以，在这两个回调函数中不可以使用对象，也不可以抛出异常。
|
||
如果在函数中抛出异常，PHP 既不会捕获它，也不会跟踪它，
|
||
这样会导致程序异常终止。
|
||
但是对象析构函数可以使用会话。
|
||
</para>
|
||
<para>
|
||
可以在析构函数中调用 <function>session_write_close</function>
|
||
函数来解决这个问题。
|
||
但是注册 shutdown 回调函数才是更加可靠的做法。
|
||
</para>
|
||
</warning>
|
||
<warning>
|
||
<para>
|
||
如果会话在脚本结束后关闭，对于某些 SAPI 而言，当前工作目录可能已经被改变。
|
||
可以调用 <function>session_write_close</function>
|
||
函数在脚本执行结束之前关闭会话。
|
||
</para>
|
||
</warning>
|
||
</refsect1>
|
||
<refsect1 role="seealso">
|
||
&reftitle.seealso;
|
||
<para>
|
||
<simplelist>
|
||
<member>
|
||
<link linkend="ini.session.save-handler">session.save_handler</link>
|
||
配置指示
|
||
</member>
|
||
<member>
|
||
<link linkend="ini.session.serialize-handler">session.serialize_handler</link>
|
||
配置指示
|
||
</member>
|
||
<member><function>register_shutdown_function</function></member>
|
||
<member><function>session_register_shutdown</function></member>
|
||
<member>
|
||
完整的实现请参考
|
||
<link xlink:href="&url.session-save-handler;">save_handler.inc</link>。
|
||
</member>
|
||
</simplelist>
|
||
</para>
|
||
</refsect1>
|
||
|
||
</refentry>
|
||
|
||
<!-- Keep this comment at the end of the file
|
||
Local variables:
|
||
mode: sgml
|
||
sgml-omittag:t
|
||
sgml-shorttag:t
|
||
sgml-minimize-attributes:nil
|
||
sgml-always-quote-attributes:t
|
||
sgml-indent-step:1
|
||
sgml-indent-data:t
|
||
indent-tabs-mode:nil
|
||
sgml-parent-document:nil
|
||
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
||
sgml-exposed-tags:nil
|
||
sgml-local-catalogs:nil
|
||
sgml-local-ecat-files:nil
|
||
End:
|
||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||
vim: et tw=78 syn=sgml
|
||
vi: ts=1 sw=1
|
||
-->
|