mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 00:48:54 +00:00
a49c33ff31
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@147048 c90b9560-bf6c-de11-be94-00142212c4b1
600 lines
18 KiB
XML
600 lines
18 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.17 $ -->
|
|
<section id="session.configuration">
|
|
&reftitle.runtime;
|
|
&extension.runtime;
|
|
<para>
|
|
<table>
|
|
<title>Session configuration options</title>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Name</entry>
|
|
<entry>Default</entry>
|
|
<entry>Changeable</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>session.save_path</entry>
|
|
<entry>"/tmp"</entry>
|
|
<entry>PHP_INI_ALL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>session.name</entry>
|
|
<entry>"PHPSESSID"</entry>
|
|
<entry>PHP_INI_ALL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>session.save_handler</entry>
|
|
<entry>"files"</entry>
|
|
<entry>PHP_INI_ALL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>session.auto_start</entry>
|
|
<entry>"0"</entry>
|
|
<entry>PHP_INI_ALL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>session.gc_probability</entry>
|
|
<entry>"1"</entry>
|
|
<entry>PHP_INI_ALL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>session.gc_maxlifetime</entry>
|
|
<entry>"1440"</entry>
|
|
<entry>PHP_INI_ALL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>session.serialize_handler</entry>
|
|
<entry>"php"</entry>
|
|
<entry>PHP_INI_ALL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>session.cookie_lifetime</entry>
|
|
<entry>"0"</entry>
|
|
<entry>PHP_INI_ALL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>session.cookie_path</entry>
|
|
<entry>"/"</entry>
|
|
<entry>PHP_INI_ALL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>session.cookie_domain</entry>
|
|
<entry>""</entry>
|
|
<entry>PHP_INI_ALL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>session.cookie_secure</entry>
|
|
<entry>""</entry>
|
|
<entry>PHP_INI_ALL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>session.use_cookies</entry>
|
|
<entry>"1"</entry>
|
|
<entry>PHP_INI_ALL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>session.use_only_cookies</entry>
|
|
<entry>"0"</entry>
|
|
<entry>PHP_INI_ALL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>session.referer_check</entry>
|
|
<entry>""</entry>
|
|
<entry>PHP_INI_ALL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>session.entropy_file</entry>
|
|
<entry>""</entry>
|
|
<entry>PHP_INI_ALL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>session.entropy_length</entry>
|
|
<entry>"0"</entry>
|
|
<entry>PHP_INI_ALL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>session.cache_limiter</entry>
|
|
<entry>"nocache"</entry>
|
|
<entry>PHP_INI_ALL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>session.cache_expire</entry>
|
|
<entry>"180"</entry>
|
|
<entry>PHP_INI_ALL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>session.use_trans_sid</entry>
|
|
<entry>"0"</entry>
|
|
<entry>PHP_INI_SYSTEM | PHP_INI_PERDIR</entry>
|
|
</row>
|
|
<row>
|
|
<entry>session.bug_compat_42</entry>
|
|
<entry>"1"</entry>
|
|
<entry>PHP_INI_ALL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>session.bug_compat_warn</entry>
|
|
<entry>"1"</entry>
|
|
<entry>PHP_INI_ALL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>url_rewriter.tags</entry>
|
|
<entry>"a=href,area=href,frame=src,input=src,form=fakeentry"</entry>
|
|
<entry>PHP_INI_ALL</entry>
|
|
</row>
|
|
|
|
<!-- Not yet
|
|
<row>
|
|
<entry>session.encode_sources</entry>
|
|
<entry>"globals</entry>
|
|
<entry>track"</entry>
|
|
</row>
|
|
-->
|
|
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
For further details and definition of the PHP_INI_* constants see
|
|
<function>ini_set</function>.
|
|
</para>
|
|
<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.
|
|
<variablelist>
|
|
|
|
<varlistentry id="ini.session.save-handler">
|
|
<term>
|
|
<parameter>session.save_handler</parameter>
|
|
<type>string</type>
|
|
</term>
|
|
<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>. See also
|
|
<function>session_set_save_handler</function>.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="ini.session.save-path">
|
|
<term>
|
|
<parameter>session.save_path</parameter>
|
|
<type>string</type>
|
|
</term>
|
|
<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>. See also
|
|
<function>session_save_path</function>.
|
|
</simpara>
|
|
<para>
|
|
There is an optional N argument to this directive that determines
|
|
the number of directory levels your session files will be spread
|
|
around in. For example, setting to <literal>'5;/tmp'</literal>
|
|
may end up creating a session file and location like
|
|
<literal>/tmp/4/b/1/e/3/sess_4b1e384ad74619bd212e236e52a5a174If
|
|
</literal>. In order to use N you must create all of these
|
|
directories before use. A small shell script exists in
|
|
<filename>ext/session</filename> to do this, it's called
|
|
<filename>mod_files.sh</filename>. Also note that if N is
|
|
used and greater than 0 then automatic garbage collection will
|
|
not be performed, see a copy of &php.ini; for further
|
|
information. Also, if you use N, be sure to surround
|
|
<literal>session.save_path</literal> in
|
|
"quotes" because the separator (<literal>;</literal>) is
|
|
also used for comments in &php.ini;.
|
|
</para>
|
|
<warning>
|
|
<para>
|
|
If you leave this set to a world-readable directory, such as
|
|
<filename>/tmp</filename> (the default), other users on the
|
|
server may be able to hijack sessions by getting the list of
|
|
files in that directory.
|
|
</para>
|
|
</warning>
|
|
<note>
|
|
<simpara>
|
|
Windows users have to change this variable in order to use PHP's
|
|
session functions. Make sure to specify a valid path, e.g.:
|
|
<filename>c:/temp</filename>.
|
|
</simpara>
|
|
</note>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="ini.session.name">
|
|
<term>
|
|
<parameter>session.name</parameter>
|
|
<type>string</type>
|
|
</term>
|
|
<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>.
|
|
See also <function>session_name</function>.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="ini.session.auto-start">
|
|
<term>
|
|
<parameter>session.auto_start</parameter>
|
|
<type>boolean</type>
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<literal>session.auto_start</literal> specifies whether the
|
|
session module starts a session automatically on request
|
|
startup. Defaults to <literal>0</literal> (disabled).
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="ini.session.serialize-handler">
|
|
<term>
|
|
<parameter>session.serialize_handler</parameter>
|
|
<type>string</type>
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<literal>session.serialize_handler</literal> defines the name
|
|
of the handler which is used to serialize/deserialize
|
|
data. Currently, a PHP internal format (name
|
|
<literal>php</literal>) and WDDX is supported (name
|
|
<literal>wddx</literal>). WDDX is only available, if PHP is
|
|
compiled with <link linkend="ref.wddx">WDDX
|
|
support</link>. Defaults to <literal>php</literal>.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="ini.session.gc-probability">
|
|
<term>
|
|
<parameter>session.gc_probability</parameter>
|
|
<type>integer</type>
|
|
</term>
|
|
<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>.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="ini.session.gc-maxlifetime">
|
|
<term>
|
|
<parameter>session.gc_maxlifetime</parameter>
|
|
<type>integer</type>
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<literal>session.gc_maxlifetime</literal> specifies the number
|
|
of seconds after which data will be seen as 'garbage' and
|
|
cleaned up.
|
|
</simpara>
|
|
<note>
|
|
<simpara>If you are using the default file-based session handler, your
|
|
filesystem must keep track of access times (atime). Windows FAT does
|
|
not so you will have to come up with another way to handle garbage
|
|
collecting your session if you are stuck with a FAT filesystem or any
|
|
other fs where atime tracking is not available.
|
|
</simpara>
|
|
</note>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="ini.session.referer-check">
|
|
<term>
|
|
<parameter>session.referer_check</parameter>
|
|
<type>string</type>
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<literal>session.referer_check</literal> contains the
|
|
substring you want to check each HTTP Referer for. If the
|
|
Referer was sent by the client and the substring was not
|
|
found, the embedded session id will be marked as invalid.
|
|
Defaults to the empty string.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="ini.session.entropy-file">
|
|
<term>
|
|
<parameter>session.entropy_file</parameter>
|
|
<type>string</type>
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<literal>session.entropy_file</literal> gives a path to an
|
|
external resource (file) which will be used as an 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.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="ini.session.entropy-length">
|
|
<term>
|
|
<parameter>session.entropy_length</parameter>
|
|
<type>integer</type>
|
|
</term>
|
|
<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).
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="ini.session.use-cookies">
|
|
<term>
|
|
<parameter>session.use_cookies</parameter>
|
|
<type>boolean</type>
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<literal>session.use_cookies</literal> specifies whether the
|
|
module will use cookies to store the session id on the client
|
|
side. Defaults to <literal>1</literal> (enabled).
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="ini.session.use-only-cookies">
|
|
<term>
|
|
<parameter>session.use_only_cookies</parameter>
|
|
<type>boolean</type>
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<literal>session.use_only_cookies</literal> specifies whether
|
|
the module will <emphasis role="strong">only</emphasis> use
|
|
cookies to store the session id on the client side. Defaults
|
|
to <literal>0</literal> (disabled, for backward compatibility).
|
|
Enabling this setting prevents attacks involved passing session
|
|
ids in URLs. This setting was added in <literal>PHP</literal>
|
|
4.3.0.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry id="ini.session.cookie-lifetime">
|
|
<term>
|
|
<parameter>session.cookie_lifetime</parameter>
|
|
<type>integer</type>
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<literal>session.cookie_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>.See also
|
|
<function>session_get_cookie_params</function> and
|
|
<function>session_set_cookie_params</function>.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="ini.session.cookie-path">
|
|
<term>
|
|
<parameter>session.cookie_path</parameter>
|
|
<type>string</type>
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<literal>session.cookie_path</literal> specifies path to set
|
|
in session_cookie. Defaults to <literal>/</literal>.See also
|
|
<function>session_get_cookie_params</function> and
|
|
<function>session_set_cookie_params</function>.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="ini.session.cookie-domain">
|
|
<term>
|
|
<parameter>session.cookie_domain</parameter>
|
|
<type>string</type>
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<literal>session.cookie_domain</literal> specifies the domain to
|
|
set in session_cookie. Default is none at all. See also
|
|
<function>session_get_cookie_params</function> and
|
|
<function>session_set_cookie_params</function>.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="ini.session.cookie-secure">
|
|
<term>
|
|
<parameter>session.cookie_secure</parameter>
|
|
<type>boolean</type>
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<literal>session.cookie_secure</literal> specifies whether
|
|
cookies should only be sent over secure connections. Defaults to
|
|
<literal>off</literal>.
|
|
This setting was added in <literal>PHP</literal>
|
|
4.0.4. See also
|
|
<function>session_get_cookie_params</function> and
|
|
<function>session_set_cookie_params</function>.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="ini.session.cache-limiter">
|
|
<term>
|
|
<parameter>session.cache_limiter</parameter>
|
|
<type>string</type>
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<literal>session.cache_limiter</literal> specifies cache
|
|
control method to use for session pages
|
|
(none/nocache/private/private_no_expire/public). Defaults to
|
|
<literal>nocache</literal>. See also
|
|
<function>session_cache_limiter</function>.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry id="ini.session.cache-expire">
|
|
<term>
|
|
<parameter>session.cache_expire</parameter>
|
|
<type>integer</type>
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<literal>session.cache_expire</literal> specifies time-to-live
|
|
for cached session pages in minutes, this has no effect for
|
|
nocache limiter. Defaults to <literal>180</literal>. See also
|
|
<function>session_cache_expire</function>.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="ini.session.use-trans-sid">
|
|
<term>
|
|
<parameter>session.use_trans_sid</parameter>
|
|
<type>boolean</type>
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<literal>session.use_trans_sid</literal> whether transparent
|
|
sid support is enabled or not. Defaults to
|
|
<literal>0</literal> (disabled).
|
|
</simpara>
|
|
<note>
|
|
<simpara>
|
|
For PHP 4.1.2 or less, it is enabled by compiling with
|
|
<link linkend="install.configure.enable-trans-sid">
|
|
<literal>--enable-trans-sid</literal></link>.
|
|
From PHP 4.2.0, trans-sid feature is always compiled.
|
|
</simpara>
|
|
<simpara>
|
|
URL based session management has additional security risks
|
|
compared to cookie based session management. Users may send
|
|
an URL that contains an active session ID to their friends by
|
|
email or users may save an URL that contains a session ID to
|
|
their bookmarks and access your site with the same session ID
|
|
always, for example.
|
|
</simpara>
|
|
</note>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="ini.session.bug-compat-42">
|
|
<term>
|
|
<parameter>session.bug_compat_42</parameter>
|
|
<type>boolean</type>
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
PHP versions 4.2.0 and lower have an undocumented feature/bug that
|
|
allows you to to initialize a session variable in the global scope,
|
|
albeit <link linkend="ini.register-globals">register_globals</link>
|
|
is disabled. PHP 4.3.0 and later will warn you, if this feature is
|
|
used, and if <link linkend="ini.session.bug-compat-warn">
|
|
session.bug_compat_warn</link> is also enabled.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="ini.session.bug-compat-warn">
|
|
<term>
|
|
<parameter>session.bug_compat_warn</parameter>
|
|
<type>boolean</type>
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
PHP versions 4.2.0 and lower have an undocumented feature/bug that
|
|
allows you to to initialize a session variable in the global scope,
|
|
albeit <link linkend="ini.register-globals">register_globals</link>
|
|
is disabled. PHP 4.3.0 and later will warn you, if this feature is
|
|
used by enabling both
|
|
<link linkend="ini.session.bug-compat-42">session.bug_compat_42</link>
|
|
and <link linkend="ini.session.bug-compat-warn">
|
|
session.bug_compat_warn</link>.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="ini.url-rewriter.tags">
|
|
<term>
|
|
<parameter>url_rewriter.tags</parameter>
|
|
<type>string</type>
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<literal>url_rewriter.tags</literal> specifies which HTML tags
|
|
are rewritten to include session id if transparent sid support
|
|
is enabled. Defaults to
|
|
<literal>a=href,area=href,frame=src,input=src,form=fakeentry,fieldset=</literal>
|
|
</simpara>
|
|
<note>
|
|
<simpara>
|
|
If you want XHTML conformity, remove the <literal>form</literal> entry and
|
|
use the <fieldset> tags around your form fields.
|
|
</simpara>
|
|
</note>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
The <link
|
|
linkend="ini.track-vars"><literal>track_vars</literal></link> and
|
|
<link
|
|
linkend="ini.register-globals"><literal>register_globals</literal></link>
|
|
configuration settings influence how the session variables get
|
|
stored and restored.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
As of PHP 4.0.3, <link
|
|
linkend="ini.track-vars"><literal>track_vars</literal></link> is
|
|
always turned on.
|
|
</para>
|
|
</note>
|
|
|
|
</section>
|
|
|
|
<!-- 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:"../../../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
|
|
-->
|
|
|