cvs: phpdoc /en/reference/session/functions session-cache-expire.xml session-cache-limiter.xml session-commit.xml session-decode.xml
session-destroy.xml session-encode.xml session-get-cookie-params.xml session-id.xml session-is-registered.xml session-module-name.xml session-name.xml
session-regenerate-id.xml session-register.xml session-save-path.xml session-set-cookie-params.xml session-set-save-handler.xml session-start.xml
session-unregister.xml session-unset.xml session-write-close.xml

From:	Mehdi Achour	Date:	Fri, 15 Jun 2007 00:15:59 +0000
Subject:	cvs: phpdoc /en/reference/session/functions session-cache-expire.xml session-cache-limiter.xml session-commit.xml session-decode.xml session-destroy.xml session-encode.xml session-get-cookie-params.xml session-id.xml session-is-registered.xml session-module-name.xml session-name.xml session-regenerate-id.xml session-register.xml session-save-path.xml session-set-cookie-params.xml session-set-save-handler.xml session-start.xml session-unregister.xml session-unset.xml session-write-close.xml
Groups:	php.doc
Request:	Send a blank email to phpdoc+get-969376683@lists.php.net to get a copy of this message

didou Fri Jun 15 00:15:59 2007 UTC Modified files: /phpdoc/en/reference/session/functions session-cache-expire.xml session-cache-limiter.xml session-commit.xml session-decode.xml session-destroy.xml session-encode.xml session-get-cookie-params.xml session-id.xml session-is-registered.xml session-module-name.xml session-name.xml session-regenerate-id.xml session-register.xml session-save-path.xml session-set-cookie-params.xml session-set-save-handler.xml session-start.xml session-unregister.xml session-unset.xml session-write-close.xml Log: ref.session: new doc style

http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/session/functions/session-cache-expire.xml?r1=1.8&r2=1.9&diff_format=u Index: phpdoc/en/reference/session/functions/session-cache-expire.xml diff -u phpdoc/en/reference/session/functions/session-cache-expire.xml:1.8 phpdoc/en/reference/session/functions/session-cache-expire.xml:1.9 --- phpdoc/en/reference/session/functions/session-cache-expire.xml:1.8 Fri Jun 15 00:15:33 2007 +++ phpdoc/en/reference/session/functions/session-cache-expire.xml Fri Jun 15 00:15:59 2007 @@ -1,23 +1,20 @@ <?xml version="1.0" encoding="iso-8859-1"?> - - + <refentry id='function.session-cache-expire'> <refnamediv> <refname>session_cache_expire</refname> <refpurpose>Return current cache expire</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>session_cache_expire</methodname> <methodparam choice="opt"><type>int</type><parameter>new_cache_expire</parameter></methodparam> </methodsynopsis> <para> <function>session_cache_expire</function> returns the current setting of - <literal>session.cache_expire</literal>. The value returned should be read - in minutes, defaults to 180. If <parameter>new_cache_expire</parameter> - is given, the current cache expire is replaced with - <parameter>new_cache_expire</parameter>. + <literal>session.cache_expire</literal>. </para> <para> The cache expire is reset to the default value of 180 stored in @@ -25,9 +22,48 @@ you need to call <function>session_cache_expire</function> for every request (and before <function>session_start</function> is called). </para> - <example> - <title><function>session_cache_expire</function> example</title> - <programlisting role="php"> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>new_cache_expire</parameter></term> + <listitem> + <para> + If <parameter>new_cache_expire</parameter> is given, the current cache + expire is replaced with <parameter>new_cache_expire</parameter>. + </para> + <para> + <note> + <simpara> + Setting <parameter>new_cache_expire</parameter> is of value only, if + <literal>session.cache_limiter</literal> is set to a value + <emphasis>different</emphasis> from <literal>nocache</literal>. + </simpara> + </note> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the current setting of <literal>session.cache_expire</literal>. + The value returned should be read in minutes, defaults to 180. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>session_cache_expire</function> example</title> + <programlisting role="php"> <![CDATA[ <?php @@ -48,21 +84,22 @@ echo "The cached session pages expire after $cache_expire minutes"; ?> ]]> - </programlisting> - </example> - <note> - <simpara> - Setting <parameter>new_cache_expire</parameter> is of value only, if - <literal>session.cache_limiter</literal> is set to a value - <emphasis>different</emphasis> from <literal>nocache</literal>. - </simpara> - </note> - <para> - See also the configuration settings <link linkend="ini.session.cache-expire"> - session.cache_expire</link>, <link linkend="ini.session.cache-limiter"> - session.cache_limiter</link> and <function>session_cache_limiter</function>. + </programlisting> + </example> + </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><link linkend="ini.session.cache-expire">session.cache_expire</link></member> + <member><link linkend="ini.session.cache-limiter">session.cache_limiter</link></member> + <member><function>session_cache_limiter</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.session-cache-limiter"> <refnamediv> <refname>session_cache_limiter</refname> <refpurpose>Get and/or set the current cache limiter</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>session_cache_limiter</methodname> <methodparam choice="opt"><type>string</type><parameter>cache_limiter</parameter></methodparam> </methodsynopsis> <para> <function>session_cache_limiter</function> returns the name of the - current cache limiter. If <parameter>cache_limiter</parameter> - is specified, the name of the current cache limiter is changed to the - new value. + current cache limiter. </para> <para> The cache limiter defines which cache control HTTP headers are sent to @@ -28,17 +26,11 @@ and permits the client to cache the contents. </para> <para> - In <literal>private</literal> mode, the Expire header sent to the - client may cause confusion for some browsers, including Mozilla. - You can avoid this problem by using - <literal>private_no_expire</literal> mode. The expire header is never - sent to the client in this mode. - </para> - <note> - <para> - <literal>private_no_expire</literal> was added in PHP 4.2.0. - </para> - </note> + In <literal>private</literal> mode, the Expire header sent to the client + may cause confusion for some browsers, including Mozilla. You can avoid + this problem by using <literal>private_no_expire</literal> mode. The + expire header is never sent to the client in this mode. + </para> <para> The cache limiter is reset to the default value stored in <link linkend="ini.session.cache-limiter">session.cache_limiter</link> @@ -46,9 +38,62 @@ <function>session_cache_limiter</function> for every request (and before <function>session_start</function> is called). </para> - <example> - <title><function>session_cache_limiter</function> example</title> - <programlisting role="php"> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>cache_limiter</parameter></term> + <listitem> + <para> + If <parameter>cache_limiter</parameter> is specified, the name of the + current cache limiter is changed to the new value. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the name of the current cache limiter. + </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>4.2.0</entry> + <entry> + The <literal>private_no_expire</literal> cache limiter was added. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>session_cache_limiter</function> example</title> + <programlisting role="php"> <![CDATA[ <?php @@ -60,13 +105,20 @@ echo "The cache limiter is now set to $cache_limiter<br />"; ?> ]]> - </programlisting> - </example> + </programlisting> + </example> + </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - Also see the <link linkend="ini.session.cache-limiter">session.cache_limiter</link> - configuration directive. + <simplelist> + <member><link linkend="ini.session.cache-limiter">session.cache_limiter</link></member> + </simplelist> </para> </refsect1> + </refentry>  + <refentry id="function.session-commit"> <refnamediv> <refname>session_commit</refname> @@ -13,6 +13,7 @@ <function>session_write_close</function>. </simpara> </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> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>session_decode</methodname> <methodparam><type>string</type><parameter>data</parameter></methodparam> @@ -17,11 +17,40 @@ <parameter>data</parameter>, setting variables stored in the session. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>data</parameter></term> + <listitem> + <para> + The encoded data to be stored. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - See also - <function>session_encode</function>. + &return.success; </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>session_encode</function></member> + </simplelist> + </para> + </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> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>session_destroy</methodname> <void/> </methodsynopsis> <simpara> - <function>session_destroy</function> destroys all of the data - associated with the current session. It does not unset any of - the global variables associated with the session, or unset the - session cookie. + <function>session_destroy</function> destroys all of the data associated + with the current session. It does not unset any of the global variables + associated with the session, or unset the session cookie. </simpara> <para> In order to kill the session altogether, like to log the user out, the @@ -24,9 +23,17 @@ session id (default behavior), then the session cookie must be deleted. <function>setcookie</function> may be used for that. </para> - <simpara> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> &return.success; - </simpara> + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title>Destroying a session with <varname>$_SESSION</varname></title> @@ -53,18 +60,28 @@ </programlisting> </example> </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; <note> <para> Only use <function>session_unset</function> for older deprecated code that does not use <varname>$_SESSION</varname>. </para> </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also - <function>unset</function> and - <function>setcookie</function>. + <simplelist> + <member><function>unset</function></member> + <member><function>setcookie</function></member> + </simplelist> </para> </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> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>session_encode</methodname> <void/> @@ -16,11 +16,24 @@ <function>session_encode</function> returns a string with the contents of the current session encoded within. </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - See also - <function>session_decode</function> + Returns the contents of the current session encoded. </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>session_decode</function></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.session-get-cookie-params"> <refnamediv> <refname>session_get_cookie_params</refname> <refpurpose>Get the session cookie parameters</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>array</type><methodname>session_get_cookie_params</methodname> <void/> </methodsynopsis> <para> - The <function>session_get_cookie_params</function> function returns an - array with the current session cookie information, the array contains - the following items: + Gets the session cookie parameters. + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns an array with the current session cookie information, the array + contains the following items: <itemizedlist> <listitem> <simpara> @@ -35,27 +41,62 @@ <listitem> <simpara> "secure" - The cookie should only be sent over secure connections. - (This item was added in PHP 4.0.4.) </simpara> </listitem> <listitem> <simpara> - "httponly" - The cookie can only be accessed through the HTTP protocol - (This item was added in PHP 5.2.0). + "httponly" - The cookie can only be accessed through the HTTP protocol. </simpara> </listitem> </itemizedlist> </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; <para> - See also the configuration directives - <link linkend="ini.session.cookie-lifetime">session.cookie_lifetime</link>, - <link linkend="ini.session.cookie-path">session.cookie_path</link>, - <link linkend="ini.session.cookie-domain">session.cookie_domain</link>, - <link linkend="ini.session.cookie-secure">session.cookie_secure</link>, - <link linkend="ini.session.cookie-httponly">session.cookie_httponly</link>, and - <function>session_set_cookie_params</function>. + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>5.2.0</entry> + <entry> + The "httponly" entry was added in the returned array? + </entry> + </row> + <row> + <entry>4.0.4</entry> + <entry> + The "secure" entry was added in the returned array? + </entry> + </row> + </tbody> + </tgroup> + </informaltable> </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><link linkend="ini.session.cookie-lifetime">session.cookie_lifetime</link></member> + <member><link linkend="ini.session.cookie-path">session.cookie_path</link></member> + <member><link linkend="ini.session.cookie-domain">session.cookie_domain</link></member> + <member><link linkend="ini.session.cookie-secure">session.cookie_secure</link></member> + <member><link linkend="ini.session.cookie-httponly">session.cookie_httponly</link></member> + <member><link linkend="ini.session.cookie-lifetime">session.cookie_lifetime</link></member> + <member><function>session_set_cookie_params</function></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.session-id"> <refnamediv> <refname>session_id</refname> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/session/functions/session-is-registered.xml?r1=1.5&r2=1.6&diff_format=u Index: phpdoc/en/reference/session/functions/session-is-registered.xml diff -u phpdoc/en/reference/session/functions/session-is-registered.xml:1.5 phpdoc/en/reference/session/functions/session-is-registered.xml:1.6 --- phpdoc/en/reference/session/functions/session-is-registered.xml:1.5 Fri Jun 15 00:15:33 2007 +++ phpdoc/en/reference/session/functions/session-is-registered.xml Fri Jun 15 00:15:59 2007 @@ -1,40 +1,67 @@ <?xml version="1.0" encoding="iso-8859-1"?> - - + <refentry id="function.session-is-registered"> <refnamediv> <refname>session_is_registered</refname> <refpurpose>Find out whether a global variable is registered in a session</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>session_is_registered</methodname> <methodparam><type>string</type><parameter>name</parameter></methodparam> </methodsynopsis> <para> - <function>session_is_registered</function> returns &true; if there - is a global variable with the name <parameter>name</parameter> - registered in the current session. + Finds out whether a global variable is registered in a session. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>name</parameter></term> + <listitem> + <para> + The variable name. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + <function>session_is_registered</function> returns &true; if there is a + global variable with the name <parameter>name</parameter> registered in + the current session, &false; otherwise. + </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; <note> <para> - If <varname>$_SESSION</varname> (or - <varname>$HTTP_SESSION_VARS</varname> for PHP 4.0.6 or less) is - used, use <function>isset</function> to check a variable is - registered in <varname>$_SESSION</varname>. + If <varname>$_SESSION</varname> (or <varname>$HTTP_SESSION_VARS</varname> + for PHP 4.0.6 or less) is used, use <function>isset</function> to check a + variable is registered in <varname>$_SESSION</varname>. </para> </note> <caution> <para> - If you are using - <varname>$_SESSION</varname> (or <varname>$HTTP_SESSION_VARS</varname>), - do not use <function>session_register</function>, + If you are using <varname>$_SESSION</varname> + (or <varname>$HTTP_SESSION_VARS</varname>), do not use + <function>session_register</function>, <function>session_is_registered</function> and <function>session_unregister</function>. </para> </caution> </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> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>session_module_name</methodname> <methodparam choice="opt"><type>string</type><parameter>module</parameter></methodparam> </methodsynopsis> <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. + <function>session_module_name</function> gets the name of the current + session module. </para> </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>module</parameter></term> + <listitem> + <para> + If <parameter>module</parameter> is specified, that module will be + used instead. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the name of the current session module. + </para> + </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> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>session_name</methodname> <methodparam choice="opt"><type>string</type><parameter>name</parameter></methodparam> </methodsynopsis> <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. + session. </para> <para> - The session name references the session id in cookies and - URLs. It should contain only alphanumeric characters; it should - be short and descriptive (i.e. for users with enabled cookie - warnings). The session name is reset to the default value - stored in <literal>session.name</literal> at request startup - time. Thus, you need to call <function>session_name</function> - for every request (and before <function>session_start</function> - or <function>session_register</function> are called). - </para> - <warning> - <para> - The session name can't consist of digits only, at least one letter must - be present. Otherwise a new session id is generated every time. - </para> - </warning> - <example> - <title><function>session_name</function> examples</title> - <programlisting role="php"> + The session name is reset to the default value stored in + <literal>session.name</literal> at request startup time. Thus, you need to + call <function>session_name</function> for every request (and before + <function>session_start</function> or <function>session_register</function> + are called). + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>name</parameter></term> + <listitem> + <para> + The session name references the session id in cookies and URLs. It + should contain only alphanumeric characters; it should be short and + descriptive (i.e. for users with enabled cookie warnings). + If <parameter>name</parameter> is specified, the name of the current + session is changed to its value. + </para> + <para> + <warning> + <para> + The session name can't consist of digits only, at least one letter + must be present. Otherwise a new session id is generated every time. + </para> + </warning> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the name of the current session. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>session_name</function> example</title> + <programlisting role="php"> <![CDATA[ <?php @@ -46,13 +76,23 @@ echo "The previous session name was $previous_name<br />"; ?> ]]> - </programlisting> - </example> + </programlisting> + </example> + </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also the <link linkend="ini.session.name">session.name</link> - configuration directive. + <simplelist> + <member> + The <link linkend="ini.session.name">session.name</link> configuration + directive + </member> + </simplelist> </para> </refsect1> + </refentry>  + <refentry id="function.session-regenerate-id"> <refnamediv> <refname>session_regenerate_id</refname> @@ -7,6 +7,7 @@ Update the current session id with a newly generated one </refpurpose> </refnamediv> + <refsect1 role="description"> &reftitle.description; <methodsynopsis> @@ -112,6 +113,7 @@ </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.session-register"> <refnamediv> <refname>session_register</refname> <refpurpose>Register one or more global variables with the current session</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>session_register</methodname> <methodparam><type>mixed</type><parameter>name</parameter></methodparam> @@ -20,52 +20,6 @@ each name, <function>session_register</function> registers the global variable with that name in the current session. </para> - <caution> - <para> - If you want your script to work regardless of <link - linkend="ini.register-globals">register_globals</link>, - you need to instead use the - <link linkend="reserved.variables.session">$_SESSION</link> array - as <varname>$_SESSION</varname> entries are automatically - registered. If your script uses - <function>session_register</function>, it will not work in - environments where the PHP directive - <link linkend="ini.register-globals">register_globals</link> - is disabled. - </para> - </caution> - - &note.registerglobals; - - <caution> - <para> - This registers a <emphasis>global</emphasis> variable. If you - want to register a session variable from within a function, you - need to make sure to make it global using the <link - linkend="language.variables.scope"><command>global</command></link> - keyword or the <varname>$GLOBALS[]</varname> array, or use the - special session arrays as noted below. - </para> - </caution> - <caution> - <para> - If you are using <varname>$_SESSION</varname> - (or <varname>$HTTP_SESSION_VARS</varname>), do not use - <function>session_register</function>, - <function>session_is_registered</function>, and - <function>session_unregister</function>. - </para> - </caution> - <para> - This function returns &true; when all of the variables are successfully - registered with the session. - </para> - <para> - If <function>session_start</function> was not called before this function - is called, an implicit call to <function>session_start</function> with no - parameters will be made. <varname>$_SESSION</varname> does not mimic - this behavior and requires <function>session_start</function> before use. - </para> <para> You can also create a session variable by simply setting the appropriate member of the <varname>$_SESSION</varname> @@ -88,31 +42,109 @@ </programlisting> </informalexample> </para> + <para> + If <function>session_start</function> was not called before this function + is called, an implicit call to <function>session_start</function> with no + parameters will be made. <varname>$_SESSION</varname> does not mimic + this behavior and requires <function>session_start</function> before use. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>name</parameter></term> + <listitem> + <para> + A string holding the name of a variable or an array consisting of + variable names or other arrays. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + &return.success; + </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; + <caution> + <para> + If you want your script to work regardless of <link + linkend="ini.register-globals">register_globals</link>, you need to + instead use the <link + linkend="reserved.variables.session">$_SESSION</link> array as + <varname>$_SESSION</varname> entries are automatically registered. If + your script uses <function>session_register</function>, it will not work + in environments where the PHP directive <link + linkend="ini.register-globals">register_globals</link> is disabled. + </para> + </caution> + &note.registerglobals; + <caution> + <para> + This registers a <emphasis>global</emphasis> variable. If you want to + register a session variable from within a function, you need to make sure + to make it global using the <link + linkend="language.variables.scope"><command>global</command></link> + keyword or the <varname>$GLOBALS[]</varname> array, or use the special + session arrays as noted below. + </para> + </caution> + <caution> + <para> + If you are using <varname>$_SESSION</varname> + (or <varname>$HTTP_SESSION_VARS</varname>), do not use + <function>session_register</function>, + <function>session_is_registered</function>, and + <function>session_unregister</function>. + </para> + </caution> <note> <para> - It is currently impossible to register resource variables in a - session. For example, you cannot create a connection to a - database and store the connection id as a session variable and - expect the connection to still be valid the next time the - session is restored. PHP functions that return a resource are - identified by having a return type of - <literal>resource</literal> in their function definition. A - list of functions that return resources are available in the - <link linkend="resource">resource types</link> appendix. + It is currently impossible to register resource variables in a session. + For example, you cannot create a connection to a database and store the + connection id as a session variable and expect the connection to still be + valid the next time the session is restored. PHP functions that return a + resource are identified by having a return type of + <literal>resource</literal> in their function definition. A list of + functions that return resources are available in the <link + linkend="resource">resource types</link> appendix. </para> <para> - If <varname>$_SESSION</varname> (or - <varname>$HTTP_SESSION_VARS</varname> for PHP 4.0.6 or less) is - used, assign values to + If <varname>$_SESSION</varname> (or <varname>$HTTP_SESSION_VARS</varname> + for PHP 4.0.6 or less) is used, assign values to <varname>$_SESSION</varname>. For example: $_SESSION['var'] = 'ABC'; </para> </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>session_is_registered</function>, - <function>session_unregister</function>, and - <link linkend="reserved.variables.session">$_SESSION</link>. + <simplelist> + <member><function>session_is_registered</function></member> + <member><function>session_unregister</function></member> + <member><link linkend="reserved.variables.session">$_SESSION</link></member> + </simplelist> </para> </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> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>session_save_path</methodname> <methodparam choice="opt"><type>string</type><parameter>path</parameter></methodparam> </methodsynopsis> <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. - <function>session_save_path</function> needs to be called before - <function>session_start</function> for that purpose. - <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. - </para> - </note> + directory used to save session data. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>path</parameter></term> + <listitem> + <para> + Session data path. If specified, the path to which data is saved will + be changed. <function>session_save_path</function> needs to be called + before <function>session_start</function> for that purpose. + </para> + <para> + <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. + </para> + </note> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - See also the <link linkend="ini.session.save-path">session.save_path</link> - configuration directive. + Returns the path of the current directory used for data storage. </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member> + The <link linkend="ini.session.save-path">session.save_path</link> + configuration directive + </member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.session-set-cookie-params"> <refnamediv> <refname>session_set_cookie_params</refname> <refpurpose>Set the session cookie parameters</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>void</type><methodname>session_set_cookie_params</methodname> <methodparam><type>int</type><parameter>lifetime</parameter></methodparam> @@ -22,23 +22,109 @@ call <function>session_set_cookie_params</function> for every request and before <function>session_start</function> is called. </para> - <note> - <para> - The <parameter>secure</parameter> parameter was added in PHP - 4.0.4, while the <parameter>httponly</parameter> parameter was added in - PHP 5.2.0. - </para> - </note> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>lifetime</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>path</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>domain</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>secure</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>httponly</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - See also the configuration directives - <link linkend="ini.session.cookie-lifetime">session.cookie_lifetime</link>, - <link linkend="ini.session.cookie-path">session.cookie_path</link>, - <link linkend="ini.session.cookie-domain">session.cookie_domain</link>, - <link linkend="ini.session.cookie-secure">session.cookie_secure</link>, - <link linkend="ini.session.cookie-httponly">session.cookie_httponly</link>, and - <function>session_get_cookie_params</function>. + &return.void; </para> </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>5.2.0</entry> + <entry> + The <parameter>httponly</parameter> parameter was added. + </entry> + </row> + <row> + <entry>4.0.4</entry> + <entry> + The <parameter>secure</parameter> parameter was added. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member> + <link linkend="ini.session.cookie-lifetime">session.cookie_lifetime</link> + </member> + <member> + <link linkend="ini.session.cookie-domain">session.cookie_domain</link> + </member> + <member> + <link linkend="ini.session.cookie-secure">session.cookie_secure</link> + </member> + <member> + <link linkend="ini.session.cookie-httponly">session.cookie_httponly</link> + </member> + <member><function>session_get_cookie_params</function></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.session-set-save-handler"> <refnamediv> <refname>session_set_save_handler</refname> <refpurpose>Sets user-level session storage functions</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>session_set_save_handler</methodname> <methodparam><type>callback</type><parameter>open</parameter></methodparam> @@ -23,44 +23,90 @@ retrieving data associated with a session. This is most useful when a storage method other than those supplied by PHP sessions is preferred. i.e. Storing the session data in a local database. - &return.success; </para> - <note> - <para> - The "write" handler is not executed until after the output - stream is closed. Thus, output from debugging statements in the - "write" handler will never be seen in the browser. If debugging - output is necessary, it is suggested that the debug output be - written to a file instead. - </para> - </note> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - The following example provides file based session - storage similar to the PHP sessions default save handler - <parameter>files</parameter>. This example could easily be - extended to cover database storage using your favorite PHP - supported database engine. + <variablelist> + <varlistentry> + <term><parameter>open</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>close</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>read</parameter></term> + <listitem> + <para> + Read function must return string value always to make save handler + work as expected. Return empty string if there is no data to read. + Return values from other handlers are converted to boolean expression. + &true; for success, &false; for failure. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>write</parameter></term> + <listitem> + <para> + <note> + <para> + The "write" handler is not executed until after the output stream is + closed. Thus, output from debugging statements in the "write" + handler will never be seen in the browser. If debugging output is + necessary, it is suggested that the debug output be written to a + file instead. + </para> + </note> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>destroy</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>gc</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - Read function must return string value always to make save - handler work as expected. Return empty string if there is no data - to read. Return values from other handlers are converted to - boolean expression. &true; for success, &false; for failure. + &return.success; </para> - <warning> - <para> - Write and Close handlers are called after destructing objects since PHP - 5.0.5. Thus destructors can use sessions but session handler can't use - objects. In prior versions, they were called in the opposite order. It - is possible to call <function>session_write_close</function> from the - destructor to solve this chicken and egg problem. - </para> - </warning> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> - <title> - <function>session_set_save_handler</function> example - </title> + <title><function>session_set_save_handler</function> example</title> + <para> + The following example provides file based session storage similar to the + PHP sessions default save handler <parameter>files</parameter>. This + example could easily be extended to cover database storage using your + favorite PHP supported database engine. + </para> <programlisting role="php"> <![CDATA[ <?php @@ -131,11 +177,33 @@ </programlisting> </example> </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; + <warning> + <para> + Write and Close handlers are called after destructing objects since PHP + 5.0.5. Thus destructors can use sessions but session handler can't use + objects. In prior versions, they were called in the opposite order. It + is possible to call <function>session_write_close</function> from the + destructor to solve this chicken and egg problem. + </para> + </warning> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also the <link linkend="ini.session.save-handler">session.save_handler</link> - configuration directive. + <simplelist> + <member> + The <link linkend="ini.session.save-handler">session.save_handler</link> + configuration directive + </member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.session-start"> <refnamediv> <refname>session_start</refname> <refpurpose>Initialize session data</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>session_start</methodname> <void/> </methodsynopsis> - <simpara> - <function>session_start</function> creates a session or resumes - the current one based on the current session id that's being - passed via a request, such as GET, POST, or a cookie. - </simpara> - <simpara> + <para> + <function>session_start</function> creates a session or resumes the + current one based on the current session id that's being passed via a + request, such as GET, POST, or a cookie. + </para> + <para> + If you want to use a named session, you must call + <function>session_name</function> before calling + <function>session_start</function>. + </para> + <para> + <function>session_start</function> will register internal output handler + for URL rewriting when <literal>trans-sid</literal> is enabled. If a user + uses <literal>ob_gzhandler</literal> or like with + <function>ob_start</function>, the order of output handler is important + for proper output. For example, user must register + <literal>ob_gzhandler</literal> before session start. + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> This function always returns &true;. - </simpara> - <note> - <para> - If you are using cookie-based sessions, you must call - <function>session_start</function> before anything is outputted to the - browser. - </para> - </note> + </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>4.3.3</entry> + <entry> + As of now, calling <function>session_start</function> while the + session has already been started will result in an error of level + <constant>E_NOTICE</constant>. Also, the second session start will + simply be ignored. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title>A session example: <filename>page1.php</filename></title> @@ -84,40 +125,39 @@ </programlisting> </example> </para> - <simpara> - If you want to use a named session, you must call - <function>session_name</function> before calling - <function>session_start</function>. - </simpara> - <simpara> - <function>session_start</function> will register internal output - handler for URL rewriting when <literal>trans-sid</literal> is - enabled. If a user uses <literal>ob_gzhandler</literal> or like - with <function>ob_start</function>, the order of output handler - is important for proper output. For example, user must register - <literal>ob_gzhandler</literal> before session start. - </simpara> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; <note> - <simpara> - Use of <link linkend="ini.zlib.output-compression">zlib.output_compression</link> - is recommended rather than <function>ob_gzhandler</function> - </simpara> + <para> + If you are using cookie-based sessions, you must call + <function>session_start</function> before anything is outputted to the + browser. + </para> </note> <note> <para> - As of PHP 4.3.3, calling <function>session_start</function> while the - session has already been started will result in an error of level - <constant>E_NOTICE</constant>. Also, the second session start will - simply be ignored. + Use of <link linkend="ini.zlib.output-compression">zlib.output_compression</link> + is recommended rather than <function>ob_gzhandler</function> </para> </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also - <link linkend="reserved.variables.session">$_SESSION</link>, - <link linkend="ini.session.auto-start">session.auto_start</link>, and - <function>session_id</function>. + <simplelist> + <member><link linkend="reserved.variables.session">$_SESSION</link></member> + <member> + The <link linkend="ini.session.auto-start">session.auto_start</link> + configuration directive + </member> + <member><function>session_id</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.session-unregister"> <refnamediv> <refname>session_unregister</refname> <refpurpose>Unregister a global variable from the current session</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>session_unregister</methodname> <methodparam><type>string</type><parameter>name</parameter></methodparam> </methodsynopsis> <para> - <function>session_unregister</function> unregisters - the global variable named <parameter>name</parameter> from the - current session. + <function>session_unregister</function> unregisters the global variable + named <parameter>name</parameter> from the current session. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - This function returns &true; when the variable is successfully - unregistered from the session. + <variablelist> + <varlistentry> + <term><parameter>name</parameter></term> + <listitem> + <para> + The variable name. + </para> + </listitem> + </varlistentry> + </variablelist> </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + &return.success; + </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; <note> <para> - If <varname>$_SESSION</varname> (or - <varname>$HTTP_SESSION_VARS</varname> for PHP 4.0.6 or less) is - used, use <function>unset</function> to unregister a session - variable. Do not <function>unset</function> <varname>$_SESSION</varname> - itself as this will disable the special function of the - <varname>$_SESSION</varname> superglobal. + If <varname>$_SESSION</varname> (or <varname>$HTTP_SESSION_VARS</varname> + for PHP 4.0.6 or less) is used, use <function>unset</function> to + unregister a session variable. Do not <function>unset</function> + <varname>$_SESSION</varname> itself as this will disable the special + function of the <varname>$_SESSION</varname> superglobal. </para> </note> <caution> @@ -41,14 +62,15 @@ </caution> <caution> <para> - If you are using - <varname>$_SESSION</varname> (or <varname>$HTTP_SESSION_VARS</varname>), - do not use <function>session_register</function>, + If you are using <varname>$_SESSION</varname> (or + <varname>$HTTP_SESSION_VARS</varname>), do not use + <function>session_register</function>, <function>session_is_registered</function> and <function>session_unregister</function>. </para> </caution> </refsect1> + </refentry>  - + <refentry id="function.session-unset"> <refnamediv> <refname>session_unset</refname> <refpurpose>Free all session variables</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>void</type><methodname>session_unset</methodname> <void/> @@ -16,25 +16,34 @@ The <function>session_unset</function> function frees all session variables currently registered. </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + &return.success; + </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; <note> <para> - If <varname>$_SESSION</varname> (or - <varname>$HTTP_SESSION_VARS</varname> for PHP 4.0.6 or less) is - used, use <function>unset</function> to unregister a session - variable, i.e. <literal>unset ($_SESSION['varname']);</literal>. + If <varname>$_SESSION</varname> (or <varname>$HTTP_SESSION_VARS</varname> + for PHP 4.0.6 or less) is used, use <function>unset</function> to + unregister a session variable, i.e. + <literal>unset ($_SESSION['varname']);</literal>. </para> </note> - <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> + <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> </refsect1> + </refentry>  - + <refentry id="function.session-write-close"> <refnamediv> <refname>session_write_close</refname> <refpurpose>Write session data and end session</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>void</type><methodname>session_write_close</methodname> <void/> @@ -16,16 +16,23 @@ End the current session and store session data. </para> <para> - Session data is usually stored after your script terminated - without the need to call <function>session_write_close</function>, but as - session data is locked to prevent concurrent writes only one - script may operate on a session at any time. When using framesets - together with sessions you will experience the frames loading one - by one due to this locking. You can reduce the time needed to - load all the frames by ending the session as soon as all changes - to session variables are done. + Session data is usually stored after your script terminated without the + need to call <function>session_write_close</function>, but as session data + is locked to prevent concurrent writes only one script may operate on a + session at any time. When using framesets together with sessions you will + experience the frames loading one by one due to this locking. You can + reduce the time needed to load all the frames by ending the session as + soon as all changes to session variables are done. </para> </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + &return.success; + </para> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file