leszek Tue Oct 30 07:31:32 2001 EDT
Added files:
/phpdoc/pl/functions session.xml
Log:
Update: new chapter, updated some other chapters
Index: phpdoc/pl/functions/session.xml
+++ phpdoc/pl/functions/session.xml
<?xml encoding="iso-8859-2"?>
<!-- $Revision: 1.1 $ -->
<reference id="ref.session">
<title>Funkje obsługi sesji</title>
<titleabbrev>Sesje</titleabbrev>
<partintro>
<para>
Obsługa sesji w PHP ma na celu zapewnienie sposobu na zachowanie pewnych
danych w trakcie następujących po sobie wywołań strony. Pozwala to na
budowanie bardziej spersonalizowanych aplikacji i zwiększenie
atrakcyjności twojej strony internetowej.
</para>
<para>
Jeśli jesteś zaznajomiony z zarządzaniem sesją w PHPLIB, zauważysz że
pewnie koncepcje są podobne w obłudze sesji PHP.
</para>
<para>
Gość wchodzący na twoją stronę WWW otrzymuje unikalny identyfikator, tzw.
id sesji. Jest ono przechowywane albo jako ciasteczko po stronie
użytkownika lub propagowane w URL'u.
</para>
<para>
Obsługa sesji pozwala ci na rejestrowanie dowolnej ilości zmiennych, które
mają być przekazywane pomiędzy stronami. Kiedy gość wchodzi na twoją
strone, PHP automatycznie sprawdzi (jeśli session.auto_start jest ustawione
na 1) lub na twoje życzenie (jawnie przez wywołanie
<function>session_start</function> lub niejawnie przez wywołanie
<function>session_register</function>) czy specyficzne id sesji zostało
przypisane. Jeśli tak, poprzednio zachowane środowisko jest odtwarzane.
</para>
<para>
Wszystkie zarejestrowane zmienne są serializowane po wykonaniu całego kodu
strony. Zarejestrowane zmienne, które są niezdefiniowane, są zaznaczane
jako niezdefijiowane. Nie są one definiowane przez moduł sesji w
następujących po sobie wywołaniach, chyba że użytkownik zdefiniuje je
później.
</para>
<para>
Opcje konfiguracyjne <link
linkend="ini.track-vars"><literal>track_vars</literal></link> i
<link
linkend="ini.register-globals"><literal>register_globals</literal></link>
wpływają na to, jak zmienne sesyjne są przechowywane i odtwarzane.
</para>
<note>
<para>
Od PHP w wersji 4.0.3 opcja <link
linkend="ini.track-vars"><literal>track_vars</literal></link> jest zawsze
włączona.
</para>
</note>
<para>
Jeśli włączona jest opcja <link
linkend="ini.track-vars"><literal>track_vars</literal></link> a
<link
linkend="ini.register-globals"><literal>register_globals</literal></link>
jest wyłączona, tylko pozycje należące do zmiennej asocjacyjnej
$HTTP_SESSION_VARS mogą być zarejestrowane jako zmienne sesyjne.
Odtworzone zmienne sesyjne będą dostępne tylko w zmiennej
$HTTP_SESSION_VARS.
<example>
<title>
Rejestracja zmiennej z włączoną opcją <link
linkend="ini.track-vars"><literal>track_vars</literal></link>
</title>
<programlisting role="php">
<?php
session_register("count");
$HTTP_SESSION_VARS["count"]++;
?>
</programlisting>
</example>
</para>
<para>
Jeśli włączona jest opcja <link
linkend="ini.register-globals"><literal>register_globals</literal></link>,
wszystkie globalne zmienne mogą być zarejestrowane jako zmienne sesyjne a
zmienne sesyjne będą odtworzone do odpowiadających im zmiennych
globalnych.
<example>
<title>
Rejestracja zminnych z włączoną opcją <link
linkend="ini.register-globals"><literal>register_globals</literal></link>
</title>
<programlisting role="php">
<?php
session_register("count");
$count++;
?>
</programlisting>
</example>
</para>
<para>
Jeśli włączone są obie opcje, <link
linkend="ini.track-vars"><literal>track_vars</literal></link> i
<link
linkend="ini.register-globals"><literal>register_globals</literal></link>,
globalne zmienne i wpisy w $HTTP_SESSION_VARS będą referencjami do tej
samej wartości.
</para>
<para>
Istnieją dwie metody propagacji identyfikatora sesji:
<itemizedlist>
<listitem>
<simpara>
Ciasteczka
</simpara>
</listitem>
<listitem>
<simpara>
Parametry URL'a
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
Moduł sesji obsługuje obie metody. Ciasteczka są metodą optymalną, ale
ponieważ nie są one pewne (klienci nie muszą ich akceptować), nie możęmy
na nich polegać. Druga metora wstawia identyfikatory sesji bezpośrednio do
URL'i.
</para>
<para>
PHP is capable of doing this transparently when compiled with
<link linkend="install.configure.enable-trans-sid">
<literal>--enable-trans-sid</literal></link>. 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 appropriate cookie. <literal>SID</literal> is either of
the form <literal>session_name=session_id</literal> or is an empty
string.
</para>
<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 role="php">
<?php
session_register ("count");
$count++;
?>
Hello visitor, you have seen this page <?php echo $count; ?> times.<p>
<php?
# 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>
<para>
The <literal><?=SID?></literal> is not necessary, if
<link linkend="install.configure.enable-trans-sid">
<literal>--enable-trans-sid</literal></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 SID, as it would be a security risk to
leak the SID to a different server.
</para>
</note>
<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>
<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>.
</simpara>
</listitem>
<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>.
</simpara>
<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>
</listitem>
<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>.
</simpara>
</listitem>
<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>
<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>.
</simpara>
</listitem>
<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>
<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>
<listitem>
<simpara>
<literal>session.gc_maxlifetime</literal> specifies the number
of seconds after which data will be seen as 'garbage' and
cleaned up.
</simpara>
</listitem>
<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>
<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>
<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>
<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>
<listitem>
<simpara>
<literal>session.cookie_path</literal> specifies path to set
in session_cookie. Defaults to <literal>/</literal>.
</simpara>
</listitem>
<listitem>
<simpara>
<literal>session.cookie_domain</literal> specifies domain to
set in session_cookie. Default is none at all.
</simpara>
</listitem>
<listitem>
<simpara>
<literal>session.cache_limiter</literal> specifies cache control
method to use for session pages (nocache/private/public).
Defaults to <literal>nocache</literal>.
</simpara>
</listitem>
<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>.
</simpara>
</listitem>
<listitem>
<simpara>
<literal>session.use_trans_sid</literal> whether transient sid support
is enabled or not if enabled by compiling with
<link linkend="install.configure.enable-trans-sid">
<literal>--enable-trans-sid</literal></link>.
Defaults to <literal>1</literal> (enabled).
</simpara>
</listitem>
<listitem>
<simpara>
<literal>url_rewriter.tags</literal> spefifies which html tags are
rewritten to include session id if transient sid support is enabled.
Defaults to
<literal>a=href,area=href,frame=src,input=src,form=fakeentry</literal>
</simpara>
</listitem>
</itemizedlist>
<note>
<para>
Session handling was added in PHP 4.0.
</para>
</note>
</para>
</partintro>
<refentry id="function.session-start">
<refnamediv>
<refname>session_start</refname>
<refpurpose>Initialize session data</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>session_start</function></funcdef>
<void/>
</funcprototype>
</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>
<simpara>
This function always returns &true;.
</simpara>
<note>
<para>
This function was added in PHP 4.0.
</para>
</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>
<funcprototype>
<funcdef>bool <function>session_destroy</function></funcdef>
<void/>
</funcprototype>
</funcsynopsis>
<simpara>
<function>session_destroy</function> destroys all of the data
associated with the current session.
</simpara>
<simpara>
This function returns &true; on success and
&false; on failure to destroy
the session data.
</simpara>
</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>
<funcprototype>
<funcdef>string <function>session_name</function></funcdef>
<paramdef>string
<parameter><optional>name</optional></parameter>
</paramdef>
</funcprototype>
</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.
</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>
<example>
<title><function>session_name</function> examples</title>
<programlisting role="php">
<?php
# set the session name to WebsiteID
$previous_name = session_name ("WebsiteID");
echo "The previous session name was $previous_name<p>";
?>
</programlisting>
</example>
<note>
<para>
This function was added in PHP 4.0.
</para>
</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>
<funcprototype>
<funcdef>string <function>session_module_name</function></funcdef>
<paramdef>string
<parameter><optional>module</optional></parameter>
</paramdef>
</funcprototype>
</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.
</para>
</note>
</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>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>session_save_path</function></funcdef>
<paramdef>string
<parameter><optional>path</optional></parameter>
</paramdef>
</funcprototype>
</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.
</para>
</note>
<note>
<para>
This function was added in PHP 4.0.
</para>
</note>
</para>
</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>
<funcprototype>
<funcdef>string <function>session_id</function></funcdef>
<paramdef>string <parameter><optional>id</optional></parameter></paramdef>
</funcprototype>
</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>
<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.
</para>
</refsect1>
</refentry>
<refentry id="function.session-register">
<refnamediv>
<refname>session_register</refname>
<refpurpose>
Register one or more variables with the current session
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>session_register</function></funcdef>
<paramdef>mixed <parameter>name</parameter></paramdef>
<paramdef>mixed
<parameter><optional>...</optional></parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>session_register</function> variable number of
arguments, any of which can be either a string holding the
variable name or an array consisting of such variable names or
other arrays. For each encountered variable name,
<function>session_register</function> registers the global
variable named by it with the current session.
</para>
<para>
This function returns &true; when the variable is successfully
registered with the session.
</para>
<note>
<para>
It is not currently possible to register resource variables in a
session. For example, you can not 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 definitions. A
list of functions that return resources are available in the
<link linkend="resource">resource types</link> appendix.
</para>
</note>
<note>
<para>
This function was added in PHP 4.0.
</para>
</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>
<funcprototype>
<funcdef>bool <function>session_unregister</function></funcdef>
<paramdef>string <parameter>name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>session_unregister</function> unregisters (forgets)
the global variable named <parameter>name</parameter> from the
current session.
</para>
<para>
This function returns &true; when the variable is successfully
unregistered from the session.
<note>
<para>
This function was added in PHP 4.0.
</para>
</note>
</para>
</refsect1>
</refentry>
<refentry id="function.session-unset">
<refnamediv>
<refname>session_unset</refname>
<refpurpose>
Free all session variables
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>session_unset</function></funcdef>
<void/>
</funcprototype>
</funcsynopsis>
<para>
The <function>session_unset</function> function free's all session variables
currently registered.
</para>
</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>
<funcprototype>
<funcdef>bool <function>session_is_registered</function></funcdef>
<paramdef>string <parameter>name</parameter></paramdef>
</funcprototype>
</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.
</para>
</note>
</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>
<funcsynopsis>
<funcprototype>
<funcdef>
array <function>session_get_cookie_params</function>
</funcdef>
<void/>
</funcprototype>
</funcsynopsis>
<para>
The <function>session_get_cookie_params</function> function returns an
array with the current session cookie information, the array contains
the following items:
<itemizedlist>
<listitem>
<simpara>
"lifetime" - The lifetime of the cookie.
</simpara>
</listitem>
<listitem>
<simpara>
"path" - The path where information is stored.
</simpara>
</listitem>
<listitem>
<simpara>
"domain" - The domain of the cookie.
</simpara>
</listitem>
</itemizedlist>
</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>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>session_set_cookie_params</function></funcdef>
<paramdef>
int <parameter>lifetime</parameter>
</paramdef>
<paramdef>
string <parameter><optional>path</optional></parameter>
</paramdef>
<paramdef>
string <parameter><optional>domain</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
Set cookie parameters defined in the php.ini file. The effect of this
function only lasts for the duration of the script.
</para>
</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>
<funcprototype>
<funcdef>bool <function>session_decode</function></funcdef>
<paramdef>string <parameter>data</parameter></paramdef>
</funcprototype>
</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.
</para>
</note>
</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>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>session_encode</function></funcdef>
<void/>
</funcprototype>
</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.
</para>
</note>
</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>
<funcsynopsis>
<funcprototype>
<funcdef>void
<function>session_set_save_handler</function>
</funcdef>
<paramdef>string
<parameter>open</parameter></paramdef><paramdef>string
<parameter>close</parameter></paramdef><paramdef>string
<parameter>read</parameter></paramdef><paramdef>string
<parameter>write</parameter></paramdef><paramdef>string
<parameter>destroy</parameter></paramdef><paramdef>string
<parameter>gc</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>session_set_save_handler</function> sets the user-level
session storage functions which are used for storing and
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.
</para>
<note>
<para>
You must set the configuration option
<parameter>session.save_handler</parameter> to
<parameter>user</parameter> in your php.ini file for
<function>session_set_save_handler</function> to take effect.
</para>
</note>
<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>
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>
<para>
<example>
<title>
<function>session_set_save_handler</function> example
</title>
<programlisting role="php">
<?php
function open ($save_path, $session_name) {
global $sess_save_path, $sess_session_name;
$sess_save_path = $save_path;
$sess_session_name = $session_name;
return(true);
}
function close() {
return(true);
}
function read ($id) {
global $sess_save_path, $sess_session_name;
$sess_file = "$sess_save_path/sess_$id";
if ($fp = @fopen($sess_file, "r")) {
$sess_data = fread($fp, filesize($sess_file));
return($sess_data);
} else {
return("");
}
}
function write ($id, $sess_data) {
global $sess_save_path, $sess_session_name;
$sess_file = "$sess_save_path/sess_$id";
if ($fp = @fopen($sess_file, "w")) {
return(fwrite($fp, $sess_data));
} else {
return(false);
}
}
function destroy ($id) {
global $sess_save_path, $sess_session_name;
$sess_file = "$sess_save_path/sess_$id";
return(@unlink($sess_file));
}
/*********************************************
* WARNING - You will need to implement some *
* sort of garbage collection routine here. *
*********************************************/
function gc ($maxlifetime) {
return true;
}
session_set_save_handler ("open", "close", "read", "write", "destroy", "gc");
session_start();
// proceed to use sessions normally
?>
</programlisting>
</example>
</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>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>session_cache_limiter</function></funcdef>
<paramdef>string
<parameter><optional>cache_limiter</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<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.
</para>
<para>
The cache limiter controls the cache control HTTP headers sent to the
client. These headers determine the rules by which the page content
may be cached. Setting the cache limiter to <literal>nocache</literal>,
for example, would disallow any client-side caching. A value of
<literal>public</literal>, however, would permit caching. It can also
be set to <literal>private</literal>, which is slightly more restrictive
than <literal>public</literal>.
</para>
<para>
The cache limiter is reset to the default value stored in
<literal>session.cache_limiter</literal> at request startup time. Thus,
you need to call <function>session_cache_limiter</function> for every
request (and before <function>session_start</function> is called).
</para>
<example>
<title><function>session_cache_limiter</function> examples</title>
<programlisting role="php">
<?php
# set the cache limiter to 'private'
session_cache_limiter('private');
$cache_limiter = session_cache_limiter();
echo "The cache limiter is now set to $cache_limiter<p>";
?>
</programlisting>
</example>
<note>
<para>
This function was added in PHP 4.0.3.
</para>
</note>
</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>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>session_write_close</function></funcdef>
<void/>
</funcprototype>
</funcsynopsis>
<para>
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.
</para>
<!-- commented out until final decision on implementation
<para>
See also: <function>session_readonly</function>.
</para>
-->
</refsect1>
</refentry>
<!-- commented out until final decision on implementation
<refentry id="function.session-readonly">
<refnamediv>
<refname>session_readonly</refname>
<refpurpose>Begin session - reinitializes freezed variables, but no writeback on
request end</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>session_readonly</function></funcdef>
<void/>
</funcprototype>
</funcsynopsis>
<para>
Read in session data without locking the session data. Changing
session data is not possible, but frameset performance will be improved.
</para>
</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:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
