mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-20 10:58:54 +00:00
79dcbe011f
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@310851 c90b9560-bf6c-de11-be94-00142212c4b1
269 lines
8.9 KiB
XML
269 lines
8.9 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>
|
|
<note>
|
|
<para>
|
|
As of PHP 4.1.0, <varname>$_SESSION</varname> is available as a
|
|
global variable just like <varname>$_POST</varname>,
|
|
<varname>$_GET</varname>, <varname>$_REQUEST</varname> and so on.
|
|
Unlike <varname>$HTTP_SESSION_VARS</varname>,
|
|
<varname>$_SESSION</varname> is always global. Therefore, you do not
|
|
need to use the <link
|
|
linkend="language.variables.scope"><command>global</command></link>
|
|
keyword for <varname>$_SESSION</varname>. Please note that this
|
|
documentation has been changed to use
|
|
<varname>$_SESSION</varname> everywhere. You can substitute
|
|
<varname>$HTTP_SESSION_VARS</varname> for
|
|
<varname>$_SESSION</varname>, if you prefer the former. Also note
|
|
that you must start your session using <function>session_start</function>
|
|
before use of <varname>$_SESSION</varname> becomes available.
|
|
</para>
|
|
<para>
|
|
The keys in the <varname>$_SESSION</varname> associative
|
|
array are subject to the
|
|
same limitations as regular variable names in PHP, i.e. they cannot
|
|
start with a number and must start with a letter or underscore.
|
|
For more details see the section on
|
|
<link linkend='language.variables'>variables</link> in this manual.
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
If <link
|
|
linkend="ini.register-globals">register_globals</link>
|
|
is disabled, only members of the global associative array
|
|
<varname>$_SESSION</varname> can be registered as session
|
|
variables. The restored session variables will only be available
|
|
in the array <varname>$_SESSION</varname>.
|
|
</para>
|
|
<para>
|
|
Use of <varname>$_SESSION</varname> (or
|
|
<varname>$HTTP_SESSION_VARS</varname> with PHP 4.0.6 or less) is
|
|
recommended for improved security and code readability. With
|
|
<varname>$_SESSION</varname>, there is no need to use the
|
|
<function>session_register</function>,
|
|
<function>session_unregister</function>,
|
|
<function>session_is_registered</function> functions. Session variables
|
|
are accessible like any other variables.
|
|
<example>
|
|
<title>
|
|
Registering a variable with <varname>$_SESSION</varname>.
|
|
</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
session_start();
|
|
// Use $HTTP_SESSION_VARS with PHP 4.0.6 or less
|
|
if (!isset($_SESSION['count'])) {
|
|
$_SESSION['count'] = 0;
|
|
} else {
|
|
$_SESSION['count']++;
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>
|
|
Unregistering a variable with <varname>$_SESSION</varname> and
|
|
<link
|
|
linkend="ini.register-globals">register_globals</link> disabled.
|
|
</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
session_start();
|
|
// Use $HTTP_SESSION_VARS with PHP 4.0.6 or less
|
|
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>
|
|
<para>
|
|
If <link
|
|
linkend="ini.register-globals">register_globals</link>
|
|
is enabled, then each global variable can be registered as session
|
|
variable. Upon a restart of a session, these variables will be restored
|
|
to corresponding global variables. Since PHP must know which global
|
|
variables are registered as session variables, users need to register
|
|
variables with <function>session_register</function> function.
|
|
You can avoid this by simply setting entries in
|
|
<varname>$_SESSION</varname>.
|
|
<caution>
|
|
<para>
|
|
Before PHP 4.3.0, if you are using <varname>$_SESSION</varname> and you
|
|
have disabled <link linkend="ini.register-globals">register_globals</link>,
|
|
don't use <function>session_register</function>,
|
|
<function>session_is_registered</function> or
|
|
<function>session_unregister</function>.
|
|
Disabling <link
|
|
linkend="ini.register-globals">register_globals</link>
|
|
is recommended for both security and performance reasons.
|
|
</para>
|
|
</caution>
|
|
</para>
|
|
<para>
|
|
If <link
|
|
linkend="ini.register-globals">register_globals</link>
|
|
is enabled, then the global variables and the
|
|
<varname>$_SESSION</varname> entries will automatically reference the
|
|
same values which were registered in the prior session instance.
|
|
However, if the variable is registered by <varname>$_SESSION</varname>
|
|
then the global variable is available since the next request.
|
|
</para>
|
|
<para>
|
|
There is a defect in PHP 4.2.3 and earlier. If you register a new
|
|
session variable by using <function>session_register</function>, the
|
|
entry in the global scope and the <varname>$_SESSION</varname> entry will
|
|
not reference the same value until the next
|
|
<function>session_start</function>. I.e. a modification to the newly
|
|
registered global variable will not be reflected by the
|
|
<varname>$_SESSION</varname> entry. This has been corrected in PHP 4.3.0.
|
|
</para>
|
|
</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. Unless you are using
|
|
PHP 4.2.0 or later, you need to enable it manually when building PHP.
|
|
Under Unix, pass <link linkend="ini.session.use-trans-sid">
|
|
--enable-trans-sid</link> to configure. If this build
|
|
option and the run-time option
|
|
<literal>session.use_trans_sid</literal> are 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 seperator. 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.
|
|
</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
|
|
-->
|
|
|