svn: /phpdoc/en/trunk/ appendices/migration70/new-features.xml reference/session/functions/session-start.xml

From: Date: Mon, 21 Sep 2015 12:16:57 +0000
Subject: svn: /phpdoc/en/trunk/ appendices/migration70/new-features.xml reference/session/functions/session-start.xml
Groups: php.doc.cvs 
Request: Send a blank email to doc-cvs+get-13747@lists.php.net to get a copy of this message
aharvey Mon, 21 Sep 2015 12:16:57 +0000 Revision: http://svn.php.net/viewvc?view=revision&revision=337868 Log: Make the session option changes less session_start() specific. This also adds documentation for the new options parameter to the session_start() page. Changed paths: U phpdoc/en/trunk/appendices/migration70/new-features.xml U phpdoc/en/trunk/reference/session/functions/session-start.xml Modified: phpdoc/en/trunk/appendices/migration70/new-features.xml =================================================================== --- phpdoc/en/trunk/appendices/migration70/new-features.xml 2015-09-21 12:16:52 UTC (rev 337867) +++ phpdoc/en/trunk/appendices/migration70/new-features.xml 2015-09-21 12:16:57 UTC (rev 337868) @@ -568,8 +568,8 @@ <programlisting role="php"> <![CDATA[ <?php - var_dump(intdiv(10, 3)); +?> ]]> </programlisting> &example.outputs; @@ -581,31 +581,47 @@ </informalexample> </sect2> - <sect2 xml:id="migration70.new-features.session-start-options"> - <title><function>session_start</function> Options</title> + <sect2 xml:id="migration70.new-features.session-options"> + <title>Session options</title> <para> - This feature gives the ability to pass in an array of options to the - <function>session_start</function> function. This is used to set - session-based php.ini options: + <function>session_start</function> now accepts an <type>array</type> of + options that override the + <link linkend="session.configuration">session configuration directives</link> + normally set in php.ini. </para> + <para> + These options have also been expanded to support + <link linkend="ini.session.lazy-write">session.lazy_write</link>, which is + on by default and causes PHP to only overwrite any session file if the + session data has changed, and <literal>read_and_close</literal>, which is + an option that can only be passed to <function>session_start</function> to + indicate that the session data should be read and then the session should + immediately be closed unchanged. + </para> + + <para> + For example, to set + <link linkend="ini.session.cache-limiter">session.cache_limiter</link> to + <literal>private</literal> and immediately close the session after reading + it: + </para> + <informalexample> <programlisting role="php"> <![CDATA[ <?php - -session_start(['cache_limiter' => 'private']); // sets the session.cache_limiter option to private +session_start([ + 'cache_limiter' => 'private', + 'read_and_close' => true, +]); +?> ]]> </programlisting> </informalexample> + </sect2> - <para> - This feature also introduces a new php.ini setting (session.lazy_write) - that is, by default, set to true and means that session data is only - rewritten if it changes. - </para> - </sect2> <sect2 xml:id="migration70.new-features.preg-repace-callback-array-function"> <title><function>preg_replace_callback_array</function> Function</title> Modified: phpdoc/en/trunk/reference/session/functions/session-start.xml =================================================================== --- phpdoc/en/trunk/reference/session/functions/session-start.xml 2015-09-21 12:16:52 UTC (rev 337867) +++ phpdoc/en/trunk/reference/session/functions/session-start.xml 2015-09-21 12:16:57 UTC (rev 337868) @@ -10,7 +10,7 @@ &reftitle.description; <methodsynopsis> <type>bool</type><methodname>session_start</methodname> - <void/> + <methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam> </methodsynopsis> <para> <function>session_start</function> creates a session or resumes the @@ -44,6 +44,30 @@ </para> </refsect1> + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + <varlistentry> + <term><parameter>options</parameter></term> + <listitem> + <para> + If provided, this is an associative array of options that will override + the currently set + <link linkend="session.configuration">session configuration directives</link>. + The keys should not include the <literal>session.</literal> prefix. + </para> + <para> + In addition to the normal set of configuration directives, a + <literal>read_and_close</literal> option may also be provided. If set to + &true;, this will result in the session being closed immediately after + being read, thereby avoiding unnecessary locking if the session data + won't be changed. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> @@ -65,6 +89,12 @@ </thead> <tbody> <row> + <entry>7.0.0</entry> + <entry> + The <parameter>options</parameter> parameter was added. + </entry> + </row> + <row> <entry>5.3.0</entry> <entry> If a session fails to start, then &false; is returned. @@ -88,10 +118,13 @@ <refsect1 role="examples"> &reftitle.examples; - <para> - <example> - <title>A session example: <filename>page1.php</filename></title> - <programlisting role="php"> + <refsect2> + <title>A basic session example</title> + + <para> + <example> + <title><filename>page1.php</filename></title> + <programlisting role="php"> <![CDATA[ <?php // page1.php @@ -111,21 +144,21 @@ echo '<br /><a href="page2.php?' . SID . '">page 2</a>'; ?> ]]> - </programlisting> - </example> - </para> - <para> - After viewing <filename>page1.php</filename>, the second page - <filename>page2.php</filename> will magically contain the session - data. Read the <link linkend="ref.session">session reference</link> - for information on <link linkend="session.idpassing">propagating - session ids</link> as it, for example, explains what the constant - <constant>SID</constant> is all about. - </para> - <para> - <example> - <title>A session example: <filename>page2.php</filename></title> - <programlisting role="php"> + </programlisting> + </example> + </para> + <para> + After viewing <filename>page1.php</filename>, the second page + <filename>page2.php</filename> will magically contain the session + data. Read the <link linkend="ref.session">session reference</link> + for information on <link linkend="session.idpassing">propagating + session ids</link> as it, for example, explains what the constant + <constant>SID</constant> is all about. + </para> + <para> + <example> + <title><filename>page2.php</filename></title> + <programlisting role="php"> <![CDATA[ <?php // page2.php @@ -142,9 +175,43 @@ echo '<br /><a href="page1.php">page 1</a>'; ?> ]]> + </programlisting> + </example> + </para> + </refsect2> + <refsect2> + <title>Providing options to <function>session_start</function></title> + + <example> + <title>Overriding the cookie lifetime</title> + <programlisting role="php"> +<![CDATA[ +<?php +// This sends a persistent cookie that lasts a day. +session_start([ + 'cookie_lifetime' => 86400, +]); +?> +]]> </programlisting> </example> - </para> + + <example> + <title>Reading the session and closing it</title> + <programlisting role="php"> +<![CDATA[ +<?php +// If we know we don't need to change anything in the +// session, we can just read and close rightaway to avoid +// locking the session file and blocking other pages +session_start([ + 'cookie_lifetime' => 86400, + 'read_and_close' => true, +]); +]]> + </programlisting> + </example> + </refsect2> </refsect1> <refsect1 role="notes">

« previous php.doc.cvs (#13747) next »