svn: /phpdoc/en/trunk/ appendices/migration70/new-features.xml reference/session/functions/session-start.xml
| From: | Adam Harvey | 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">