cvs: /phpdoc/functions session.sgml

sas Tue Aug 17 11:09:41 1999 EDT Modified files: /phpdoc/functions session.sgml Log: rewrite partintro Index: phpdoc/functions/session.sgml diff -u phpdoc/functions/session.sgml:1.1 phpdoc/functions/session.sgml:1.2 --- phpdoc/functions/session.sgml:1.1 Thu Jul 22 16:53:02 1999 +++ phpdoc/functions/session.sgml Tue Aug 17 11:09:39 1999 @@ -3,20 +3,109 @@ <titleabbrev>Sessions</titleabbrev> <partintro> <para> - To configure the session managment system in PHP4 you can use the - following entries in your php.ini: - <informalexample><programlisting> -session_save_path = "/tmp" -session_auto_start = 0 -session_lifetime = 0 ; lifetime in seconds -; 0 means to only use session cookies (as long as browser is open) - </programlisting></informalexample> - <para> - <systemitem>&lt;?=sid&gt;</systemitem> is a shortcut for - the session id parameter to add to a URL so the session - can be preserved without using cookies. (It is equivalent to - <systemitem>&lt;? echo <function>session_name</function> . "=" - . <function>session_id</function>;</systemitem>. + Session support in PHP4 consists of a way to preserve certain data across + subsequent accesses. This enables you to build more customized + applications and increase the something 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. + Undefined variables are stored also, but are flagged as not defined, so + they will not be defined until the user defines them. + + <para> + Currently, objects cannot be used as session variables. + + <para> + The constant <literal>SID</literal> is defined, if the session module + knows exactly that the user has accepted the cookie. You can use + <systemitem>&lt;?=SID?&gt;</systemitem> to print out the constant (this + will evaluate to an empty string, if SID is not defined). + <literal>SID</literal> is of the form + <literal>session_name=session_id</literal>. + + <para> + The following example demonstrates how to register a variable, and how to + link correctly to another page (propagation of session id). + + <example> + <title>counting the number of hits of a single user</title> + <programlisting> +&lt;?php + +session_register("count"); + +$count++; + +?&gt; + +Hello visitor, you have seen this page &lt;? echo $count; ?&gt; times.&lt;p&gt; + +# the &lt;?=SID?&gt; is necessary to preserve the session id +# in the case that the user has disabled cookies + +To continue, &lt;A HREF="nextpage.php?&lt;?=SID?&gt;"&gt;click here&lt;/A&gt; +</programlisting></example> + + <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> (off). + + <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. + + </itemizedlist> <note> <para>