session-cache-limiter.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.session-cache-limiter" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>session_cache_limiter</refname>
  <refpurpose>Get and/or set the current cache limiter</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>string</type><type>false</type></type><methodname>session_cache_limiter</methodname>
   <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>value</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>session_cache_limiter</function> returns the name of the
   current cache limiter.
  </para>
  <para>
   The cache limiter defines which cache control HTTP headers are sent to
   the client.  These headers determine the rules by which the page content
   may be cached by the client and intermediate proxies.  Setting the cache
   limiter to <literal>nocache</literal> disallows any client/proxy caching.
   A value of <literal>public</literal> permits caching by proxies and the
   client, whereas <literal>private</literal> disallows caching by proxies
   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 <productname>Mozilla</productname>.
   You can avoid this problem by using <literal>private_no_expire</literal> mode. The
   <literal>Expire</literal> header is never sent to the client in this mode.
  </para>
  <para>
   Setting the cache limiter to <literal>''</literal> will turn off automatic sending
   of cache headers entirely.
  </para>
  <para>
   The cache limiter is reset to the default value stored in
   <link linkend="ini.session.cache-limiter">session.cache_limiter</link>
   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>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>value</parameter></term>
     <listitem>
      <para>
       If <parameter>value</parameter> is specified and not &null;, the name of the
       current cache limiter is changed to the new value.
      </para>
      <table>
       <title>Possible values</title>
       <tgroup cols="2">
        <thead>
         <row>
          <entry>Value</entry>
          <entry>Headers sent</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry><literal>public</literal></entry>
          <entry>
           <programlisting role="header">
<![CDATA[
Expires: (sometime in the future, according session.cache_expire)
Cache-Control: public, max-age=(sometime in the future, according to session.cache_expire)
Last-Modified: (the timestamp of when the session was last saved)
]]>
           </programlisting>
          </entry>
         </row>
         <row>
          <entry><literal>private_no_expire</literal></entry>
          <entry>
           <programlisting role="header">
<![CDATA[
Cache-Control: private, max-age=(session.cache_expire in the future)
Last-Modified: (the timestamp of when the session was last saved)
]]>
           </programlisting>
          </entry>
         </row>
         <row>
          <entry><literal>private</literal></entry>
          <entry>
           <programlisting role="header">
<![CDATA[
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: private, max-age=(session.cache_expire in the future)
Last-Modified: (the timestamp of when the session was last saved)
]]>
           </programlisting>
          </entry>
         </row>
         <row>
          <entry><literal>nocache</literal></entry>
          <entry>
           <programlisting role="header">
<![CDATA[
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache
]]>
           </programlisting>
          </entry>
         </row>
        </tbody>
       </tgroup>
      </table>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns the name of the current cache limiter.
   On failure to change the value, &false; is returned.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.0.0</entry>
      <entry>
       <parameter>value</parameter> is nullable now.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>session_cache_limiter</function> example</title>
    <programlisting role="php">
<![CDATA[
<?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<br />";
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><link linkend="ini.session.cache-limiter">session.cache_limiter</link></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>
<!-- 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:"~/.phpdoc/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
-->