mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-19 02:18:56 +00:00
74df8e1a02
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@12942 c90b9560-bf6c-de11-be94-00142212c4b1
450 lines
15 KiB
Text
450 lines
15 KiB
Text
<reference id="ref.session">
|
|
<title>Session handling functions</title>
|
|
<titleabbrev>Sessions</titleabbrev>
|
|
<partintro>
|
|
<para>
|
|
Session support in PHP consists of a way to preserve certain data across
|
|
subsequent accesses. This enables you to build more customized
|
|
applications and increase the appeal of your web site.
|
|
|
|
<para>
|
|
A visitor accessing your web site is assigned an unique id, the so called
|
|
session id. This is either stored in a cookie on the user side or is
|
|
propagated in the URL.
|
|
|
|
<para>
|
|
The session support allows you register arbitrary numbers of variables to
|
|
be preserved across requests. When a visitor accesses your site, PHP will
|
|
check automatically (if session.auto_start is set to 1) or on your request
|
|
(explicitly through <function>session_start</function> or implicitly
|
|
through <function>session_register</function>) whether a specific
|
|
session id has been sent with the request. If this is the case, the prior
|
|
saved environment is recreated.
|
|
|
|
<para>
|
|
All registered variables are serialized after the request finishes.
|
|
Registered variables which are undefined are marked as being not defined.
|
|
On subsequent accesses, these are not defined by the session module unless
|
|
the user defines them later.
|
|
|
|
<para>
|
|
Currently, objects cannot be used as session variables.
|
|
|
|
<para>
|
|
There are two methods to propagate a session id:
|
|
|
|
<itemizedlist>
|
|
<listitem><simpara>
|
|
Cookies
|
|
<listitem><simpara>
|
|
URL parameter
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
The session module supports both methods. Cookies are optimal, but since
|
|
they are not reliable (clients are not bound to accept them), we cannot
|
|
rely on them. The second method embeds the session id directly into URLs.
|
|
|
|
<para>
|
|
PHP is capable of doing this transparently when compiled with
|
|
<literal>--enable-trans-sid</literal>. If you enable this option, relative
|
|
URIs will be changed to contain the session id automatically.
|
|
Alternatively, you can use the constant <literal>SID</literal> which is
|
|
defined, if the client did not send the appropiate cookie.
|
|
<literal>SID</literal> is either of the form
|
|
<literal>session_name=session_id</literal> or is an empty string.
|
|
|
|
<para>
|
|
The following example demonstrates how to register a variable, and how to
|
|
link correctly to another page using SID.
|
|
|
|
<example>
|
|
<title>counting the number of hits of a single user</title>
|
|
<programlisting>
|
|
<?php
|
|
|
|
session_register("count");
|
|
|
|
$count++;
|
|
|
|
?>
|
|
|
|
Hello visitor, you have seen this page <? echo $count; ?> times.<p>
|
|
|
|
<?
|
|
# the <?=SID?> is necessary to preserve the session id
|
|
# in the case that the user has disabled cookies
|
|
?>
|
|
|
|
To continue, <A HREF="nextpage.php?<?=SID?>">click here</A>
|
|
</programlisting></example>
|
|
|
|
<para>
|
|
The <literal><?=SID?></literal> is not necessary, if
|
|
<literal>--enable-trans-sid</literal> was used to compile PHP.
|
|
|
|
<para>
|
|
The session management system supports a number of configuration options
|
|
which you can place in your php.ini file. We will give a short overview.
|
|
|
|
<itemizedlist>
|
|
<listitem><simpara>
|
|
<literal>session.save_handler</literal> defines the name of the handler
|
|
which is used for storing and retrieving data associated with a session.
|
|
Defaults to <literal>files</literal>.
|
|
|
|
<listitem><simpara>
|
|
<literal>session.save_path</literal> defines the argument which is
|
|
passed to the save handler. If you choose the default files handler,
|
|
this is the path where the files are created. Defaults to
|
|
<literal>/tmp</literal>.
|
|
|
|
<listitem><simpara>
|
|
<literal>session.name</literal> specifies the name of the session which
|
|
is used as cookie name. It should only contain alphanumeric characters.
|
|
Defaults to <literal>PHPSESSID</literal>.
|
|
|
|
<listitem><simpara>
|
|
<literal>session.auto_start</literal> specifies whether the session
|
|
module start a session automatically on request startup. Defaults to
|
|
<literal>0</literal> (disabled).
|
|
|
|
<listitem><simpara>
|
|
<literal>session.lifetime</literal> specifies the lifetime of the cookie
|
|
in seconds which is sent to the browser. The value 0 means "until the
|
|
browser is closed." Defaults to <literal>0</literal>.
|
|
|
|
<listitem><simpara>
|
|
<literal>session.serialize_handler</literal> defines the name of the
|
|
handler which is used to serialize/deserialize data. Currently, only
|
|
"php" is supported. Defaults to <literal>php</literal>.
|
|
|
|
<listitem><simpara>
|
|
<literal>session.gc_probability</literal> specifies the probability that
|
|
the gc (garbage collection) routine is started on each request in
|
|
percent. Defaults to <literal>1</literal>.
|
|
|
|
<listitem><simpara>
|
|
<literal>session.gc_maxlifetime</literal> specifies the number of
|
|
seconds after which data will be seen as 'garbage' and cleaned up.
|
|
|
|
<listitem><simpara>
|
|
<literal>session.extern_referer_check</literal> determinates whether
|
|
session ids referred to by external sites will be eliminated. If session
|
|
ids are propagated using the URL method, users not knowing about the
|
|
impact might publish session ids. This can lead to security problems
|
|
which this check tries to defeat. Defaults to <literal>0</literal>.
|
|
|
|
<listitem><simpara>
|
|
<literal>session.entropy_file</literal> gives a path to an external
|
|
resource (file) which will be used as additional entropy source in the
|
|
session id creation process. Examples are <literal>/dev/random</literal>
|
|
or <literal>/dev/urandom</literal> which are available on many Unix
|
|
systems.
|
|
|
|
<listitem><simpara>
|
|
<literal>session.entropy_length</literal> specifies the number of bytes
|
|
which will be read from the file specified above. Defaults to
|
|
<literal>0</literal> (disabled).
|
|
|
|
</itemizedlist>
|
|
|
|
<note>
|
|
<para>
|
|
Session handling was added in PHP 4.0.
|
|
</note>
|
|
</partintro>
|
|
|
|
<refentry id="function.session-start">
|
|
<refnamediv>
|
|
<refname>session_start</refname>
|
|
<refpurpose>Initialize session data</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>bool <function>session_start</function></funcdef>
|
|
<void>
|
|
</funcsynopsis>
|
|
<simpara>
|
|
<function>session_start</function> creates a session (or resumes
|
|
the current one based on the session id being passed via a GET
|
|
variable or a cookie).
|
|
<simpara>
|
|
This function always returns true.
|
|
<note>
|
|
<para>
|
|
This function was added in PHP 4.0.
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.session-destroy">
|
|
<refnamediv>
|
|
<refname>session_destroy</refname>
|
|
<refpurpose>Destroys all data registered to a session</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>bool <function>session_destroy</function></funcdef>
|
|
<void>
|
|
</funcsynopsis>
|
|
<simpara>
|
|
<function>session_destroy</function> destroys all of the data
|
|
associated with the current session.
|
|
<simpara>
|
|
This function always returns true.
|
|
<note>
|
|
<para>
|
|
This function was added in PHP 4.0.
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.session-name">
|
|
<refnamediv>
|
|
<refname>session_name</refname>
|
|
<refpurpose>Get and/or set the current session name</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>string <function>session_name</function></funcdef>
|
|
<paramdef>string <parameter><optional>name</optional></parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>session_name</function> returns the name of the current
|
|
session. If <parameter>name</parameter> is specified, the name of
|
|
the current session is changed to its value.
|
|
<example>
|
|
<title><function>session_name</function> examples</title>
|
|
<programlisting>
|
|
$username="foo";
|
|
|
|
if(isset($username)) {
|
|
session_name($username);
|
|
}
|
|
|
|
echo "Your username is " . session_name();
|
|
</programlisting>
|
|
</example>
|
|
<note>
|
|
<para>
|
|
This function was added in PHP 4.0.
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.session-module-name">
|
|
<refnamediv>
|
|
<refname>session_module_name</refname>
|
|
<refpurpose>Get and/or set the current session module</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>string <function>session_module_name</function></funcdef>
|
|
<paramdef>string <parameter><optional>module</optional></parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>session_module_name</function> returns the name of the current
|
|
session module. If <parameter>module</parameter> is specified, that
|
|
module will be used instead.
|
|
<note>
|
|
<para>
|
|
This function was added in PHP 4.0.
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.session-save-path">
|
|
<refnamediv>
|
|
<refname>session_save_path</refname>
|
|
<refpurpose>Get and/or set the current session save path</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>string <function>session_save_path</function></funcdef>
|
|
<paramdef>string <parameter><optional>path</optional></parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>session_save_path</function> returns the path of the current
|
|
directory used to save session data. If <parameter>path</parameter>
|
|
is specified, the path to which data is saved will be changed.
|
|
<note>
|
|
<para>
|
|
On some operating systems, you may want to specify a path on
|
|
a filesystem that handles lots of small files efficiently. For
|
|
example, on Linux, reiserfs may provide better performance than
|
|
ext2fs.
|
|
</note>
|
|
<note>
|
|
<para>
|
|
This function was added in PHP 4.0.
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.session-id">
|
|
<refnamediv>
|
|
<refname>session_id</refname>
|
|
<refpurpose>Get and/or set the current session id</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>string <function>session_id</function></funcdef>
|
|
<paramdef>string <parameter><optional>id</optional></parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>session_id</function> returns the session id for the current
|
|
session. If <parameter>id</parameter> is specified, it will replace
|
|
the current session id.
|
|
<para>
|
|
directory used to save session data. If <parameter>path</parameter>
|
|
is specified, the path to which data is saved will be changed.
|
|
<para>
|
|
The constant <systemitem>SID</systemitem> can also be used to retrieve
|
|
the current name and session id as a string suitable for adding to
|
|
URLs.
|
|
<note>
|
|
<para>
|
|
This function was added in PHP 4.0.
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.session-register">
|
|
<refnamediv>
|
|
<refname>session_register</refname>
|
|
<refpurpose>Register a variable with the current session</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>bool <function>session_register</function></funcdef>
|
|
<paramdef>string <parameter>name</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>session_register</function> registers the global variable
|
|
named <parameter>name</parameter> with the current session.
|
|
<para>
|
|
This function returns true when the variable is successfully
|
|
registered with the session.
|
|
<note>
|
|
<para>
|
|
This function was added in PHP 4.0.
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.session-unregister">
|
|
<refnamediv>
|
|
<refname>session_unregister</refname>
|
|
<refpurpose>Unregister a variable from the current session</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>bool <function>session_unregister</function></funcdef>
|
|
<paramdef>string <parameter>name</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>session_unregister</function> unregisters (forgets)
|
|
the global variable named <parameter>name</parameter> from the
|
|
current session.
|
|
<para>
|
|
This function returns true when the variable is successfully
|
|
unregistered from the session.
|
|
<note>
|
|
<para>
|
|
This function was added in PHP 4.0.
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.session-is-registered">
|
|
<refnamediv>
|
|
<refname>session_is_registered</refname>
|
|
<refpurpose>Find out if a variable is registered in a session</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>bool <function>session_is_registered</function></funcdef>
|
|
<paramdef>string <parameter>name</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>session_is_registered</function> returns true if there
|
|
is a variable with the name <parameter>name</parameter> registered
|
|
in the current session.
|
|
<note>
|
|
<para>
|
|
This function was added in PHP 4.0.
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.session-decode">
|
|
<refnamediv>
|
|
<refname>session_decode</refname>
|
|
<refpurpose>Decodes session data from a string</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>bool <function>session_decode</function></funcdef>
|
|
<paramdef>string <parameter>data</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>session_decode</function> decodes the session data in
|
|
<parameter>data</parameter>, setting variables stored in the
|
|
session.
|
|
<note>
|
|
<para>
|
|
This function was added in PHP 4.0.
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.session-encode">
|
|
<refnamediv>
|
|
<refname>session_encode</refname>
|
|
<refpurpose>Encodes the current session data as a string</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>bool <function>session_encode</function></funcdef>
|
|
<void>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>session_encode</function> returns a string with the
|
|
contents of the current session encoded within.
|
|
<note>
|
|
<para>
|
|
This function was added in PHP 4.0.
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
</reference>
|
|
|
|
<!-- 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
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"../manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
-->
|