mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-19 02:18:56 +00:00
265 lines
9.7 KiB
XML
265 lines
9.7 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
|
|
<appendix xml:id="session.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
&reftitle.examples;
|
|
<section xml:id="session.examples.basic">
|
|
<title>Basic usage</title>
|
|
<para>
|
|
Sessions are a simple way to store data for individual users against a unique session ID.
|
|
This can be used to persist state information between page requests. Session IDs are normally
|
|
sent to the browser via session cookies and the ID is used to retrieve existing session data.
|
|
The absence of an ID or session cookie lets PHP know to create a new session, and generate a new
|
|
session ID.
|
|
</para>
|
|
<para>
|
|
Sessions follow a simple workflow. When a session is started, PHP will either retrieve an
|
|
existing session using the ID passed (usually from a session cookie) or if no session is passed
|
|
it will create a new session. PHP will populate the <varname>$_SESSION</varname> superglobal
|
|
with any session data after the session has started. When PHP shuts down, it will automatically
|
|
take the contents of the <varname>$_SESSION</varname> superglobal, serialize it, and send it
|
|
for storage using the session save handler.
|
|
</para>
|
|
<para>
|
|
By default, PHP uses the internal <parameter>files</parameter> save handler which
|
|
is set by <link linkend="ini.session.save-handler">session.save_handler</link>.
|
|
This saves session data on the server at the location specified by the
|
|
<link linkend="ini.session.save-path">session.save_path</link> configuration directive.
|
|
</para>
|
|
<para>
|
|
Sessions can be started manually using the <function>session_start</function> function.
|
|
If the <link linkend="ini.session.auto-start">session.auto_start</link> directive is set
|
|
to <parameter>1</parameter>, a session will automatically start on request startup.
|
|
</para>
|
|
<para>
|
|
Sessions normally shutdown automatically when PHP is finished executing a script, but can be
|
|
manually shutdown using the <function>session_write_close</function> function.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>
|
|
Registering a variable with <varname>$_SESSION</varname>.
|
|
</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
session_start();
|
|
if (!isset($_SESSION['count'])) {
|
|
$_SESSION['count'] = 0;
|
|
} else {
|
|
$_SESSION['count']++;
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>
|
|
Unregistering a variable with <varname>$_SESSION</varname>.
|
|
</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
session_start();
|
|
unset($_SESSION['count']);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<caution>
|
|
<para>
|
|
Do NOT unset the whole <varname>$_SESSION</varname> with
|
|
<literal>unset($_SESSION)</literal> as this will disable the
|
|
registering of session variables through the
|
|
<varname>$_SESSION</varname> superglobal.
|
|
</para>
|
|
</caution>
|
|
</para>
|
|
<warning>
|
|
<para>
|
|
You can't use references in session variables as there is no feasible way
|
|
to restore a reference to another variable.
|
|
</para>
|
|
</warning>
|
|
<note>
|
|
<para>
|
|
File based sessions (the default in PHP) lock the session file once a
|
|
session is opened via <function>session_start</function> or implicitly via
|
|
<link linkend="ini.session.auto-start">session.auto_start</link>. Once
|
|
locked, no other script can access the same session file until it has been
|
|
closed by the first script terminating or calling
|
|
<function>session_write_close</function>.
|
|
</para>
|
|
<para>
|
|
This is most likely to be an issue on Web sites that use AJAX heavily and
|
|
have multiple concurrent requests. The easiest way to deal with it is to
|
|
call <function>session_write_close</function> as soon as any required
|
|
changes to the session have been made, preferably early in the script.
|
|
Alternatively, a different session backend that does support concurrency
|
|
could be used.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
|
|
<section xml:id="session.idpassing">
|
|
<title>Passing the Session ID</title>
|
|
<para>
|
|
There are two methods to propagate a session id:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
Cookies
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
URL parameter
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
The session module supports both methods. Cookies are optimal, but
|
|
because they are not always available, we also provide an alternative
|
|
way. The second method embeds the session id directly into URLs.
|
|
</para>
|
|
<para>
|
|
PHP is capable of transforming links transparently. If the run-time
|
|
option <literal>session.use_trans_sid</literal> is enabled, relative
|
|
URIs will be changed to contain the session id automatically.
|
|
<note>
|
|
<para>
|
|
The <link linkend="ini.arg-separator.output">arg_separator.output</link>
|
|
&php.ini; directive allows to customize the argument separator. For full
|
|
XHTML conformance, specify &amp; there.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
<para>
|
|
Alternatively, you can use the constant <constant>SID</constant> which is
|
|
defined if the session started. If the client did not send an appropriate session
|
|
cookie, it has the form <literal>session_name=session_id</literal>.
|
|
Otherwise, it expands to an empty string. Thus, you can embed it
|
|
unconditionally into URLs.
|
|
</para>
|
|
<para>
|
|
The following example demonstrates how to register a variable, and
|
|
how to link correctly to another page using <constant>SID</constant>.
|
|
<example>
|
|
<title>Counting the number of hits of a single user</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
session_start();
|
|
|
|
if (empty($_SESSION['count'])) {
|
|
$_SESSION['count'] = 1;
|
|
} else {
|
|
$_SESSION['count']++;
|
|
}
|
|
?>
|
|
|
|
<p>
|
|
Hello visitor, you have seen this page <?php echo $_SESSION['count']; ?> times.
|
|
</p>
|
|
|
|
<p>
|
|
To continue, <a href="nextpage.php?<?php echo htmlspecialchars(SID); ?>">click
|
|
here</a>.
|
|
</p>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
The <function>htmlspecialchars</function> may be used when printing the <constant>SID</constant>
|
|
in order to prevent XSS related attacks.
|
|
</para>
|
|
<para>
|
|
Printing the <constant>SID</constant>, like shown above, is not necessary if
|
|
<link linkend="ini.session.use-trans-sid">
|
|
--enable-trans-sid</link> was used to compile PHP.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Non-relative URLs are assumed to point to external sites and
|
|
hence don't append the <constant>SID</constant>, as it would be a security risk to
|
|
leak the <constant>SID</constant> to a different server.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
|
|
<section xml:id="session.customhandler">
|
|
<title>Custom Session Handlers</title>
|
|
<para>
|
|
To implement database storage, or any other storage method, you
|
|
will need to use <function>session_set_save_handler</function> to
|
|
create a set of user-level storage functions. A session handlers may be created
|
|
using the <classname>SessionHandlerInterface</classname> or extending PHP's internal handlers by inheriting
|
|
from <classname>SessionHandler</classname>.
|
|
</para>
|
|
<para>
|
|
The callbacks specified in <function>session_set_save_handler</function> are methods
|
|
called by PHP during the life-cycle of a session: <parameter>open</parameter>, <parameter>read</parameter>,
|
|
<parameter>write</parameter> and <parameter>close</parameter> and for the housekeeping tasks:
|
|
<parameter>destroy</parameter> for deleting a session and <parameter>gc</parameter> for periodic garbage
|
|
collection.
|
|
</para>
|
|
<para>
|
|
Therefore, PHP always requires session save handlers. The default is usually the
|
|
internal 'files' save handler. A custom save handler can be set using
|
|
<function>session_set_save_handler</function>. Alternative internal save handlers are also
|
|
provided by PHP extensions, such as <parameter>sqlite</parameter>,
|
|
<parameter>memcache</parameter> and <parameter>memcached</parameter> and can be set with
|
|
<link linkend="ini.session.save-handler">session.save_handler</link>.
|
|
</para>
|
|
<para>
|
|
When the session starts, PHP will internally call the <parameter>open</parameter> handler followed by the
|
|
<parameter>read</parameter> callback which should return an encoded string exactly as it was originally
|
|
passed for storage. Once the <parameter>read</parameter> callback returns the encoded string, PHP will
|
|
decode it and then populate the resulting array into the <varname>$_SESSION</varname> superglobal.
|
|
</para>
|
|
<para>
|
|
When PHP shuts down (or when <function>session_write_close</function> is called),
|
|
PHP will internally encode the <varname>$_SESSION</varname> superglobal and pass this
|
|
along with the session ID to the <parameter>write</parameter> callback.
|
|
After the <parameter>write</parameter> callback has finished, PHP will internally invoke the
|
|
<parameter>close</parameter> callback handler.
|
|
</para>
|
|
<para>
|
|
When a session is specifically destroyed, PHP will call the <parameter>destroy</parameter> handler with
|
|
the session ID.
|
|
</para>
|
|
<para>
|
|
PHP will call the <parameter>gc</parameter> callback from time to time to
|
|
expire any session records according to the set max lifetime of a session.
|
|
This routine should delete all records from persistent storage which were
|
|
last accessed longer than the <parameter>$lifetime</parameter>.
|
|
</para>
|
|
</section>
|
|
</appendix>
|
|
|
|
<!-- 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
|
|
-->
|
|
|