Improve session_gc documentation (#4970)

* Improve wording of the main body and return values sections
* Minor updates to comments in the examples
* Incorporate permissions note from PR #4915

Author: jbafford

reference/session/functions/session-gc.xml

@@ -11,25 +11,34 @@
    <type class="union"><type>int</type><type>false</type></type><methodname>session_gc</methodname>
    <void/>
   </methodsynopsis>
-  <para>
-   <function>session_gc</function> is used to perform session data
-   GC (garbage collection). PHP does probability based session GC by
-   default.
-  </para>
-  <para>
-   Probability based GC works somewhat but it has few problems. 1) Low
-   traffic sites' session data may not be deleted within the preferred
-   duration. 2) High traffic sites' GC may be too frequent GC. 3) GC is
-   performed on the user's request and the user will experience a GC
-   delay.
-  </para>
-  <para>
-   Therefore, it is recommended to execute GC periodically for
-   production systems using, e.g., "cron" for UNIX-like systems.
-   Make sure to disable probability based GC by setting 
-   <link linkend="ini.session.gc-probability">session.gc_probability</link> 
-   to 0.
-  </para>
+  <simpara>
+   By default, PHP uses <link linkend="ini.session.gc-probability">session.gc_probability</link>
+   to run the session garbage collector probabilistically on each
+   request. There are some limitations with this approach:
+  </simpara>
+  <simplelist>
+   <member>Low traffic sites may not have their session data deleted within the preferred duration.</member>
+   <member>High traffic sites may have the garbage collector run too frequently, performing unnecessary extra work.</member>
+   <member>Garbage collection is performed on the user's request, and the user may experience a delay.</member>
+  </simplelist>
+  <simpara>
+   For production systems, it is recommended to disable the
+   probability-based garbage collection by setting
+   <link linkend="ini.session.gc-probability">session.gc_probability</link> to <literal>0</literal>
+   and explicitly trigger the garbage collector periodically, for example by using "cron" on
+   UNIX-like systems to run a script that calls <function>session_gc</function>.
+  </simpara>
+
+  <note>
+   <simpara>
+    When calling <function>session_gc</function> from a command-line php script,
+    the <link linkend="ini.session.save-path">session.save_path</link> must be set
+    to the same value as web requests, and the script must have access and delete
+    permissions for the session files. This may be affected by the user the script runs as,
+    and container or sandboxing features such as systemd's <literal>PrivateTmp=</literal>
+    option.
+   </simpara>
+  </note>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -39,23 +48,24 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   <function>session_gc</function> returns number of deleted session
-   data for success, &false; for failure.
-  </para>
-  <para>
-   Old save handlers do not return number of deleted session data, but 
-   only success/failure flag. If this is the case, number of deleted
-   session data became 1 regardless of actually deleted data.
-  </para>
+  <simpara>
+   <function>session_gc</function> returns the number of deleted session
+   entries on success, &return.falseforfailure;.
+  </simpara>
+  <note>
+   <simpara>
+    Old session save handlers do not return the number of deleted session entries, but
+    rather only a success/failure flag. If this is the case, <literal>1</literal> is returned regardless of
+    how many session entries are actually deleted.
+   </simpara>
+  </note>
  </refsect1>
 
  <refsect1 role="examples">
   &reftitle.examples;
-  <para>
-   <example>
-    <title><function>session_gc</function> example for task managers like cron</title>
-    <programlisting role="php">
+  <example>
+   <title><function>session_gc</function> example for task managers like cron</title>
+   <programlisting role="php">
 <![CDATA[
 <?php
 // Note: This script should be executed by the same user of web server process.
@@ -66,18 +76,18 @@ session_start();
 // Executes GC immediately
 session_gc();
 
-// Clean up session ID created by session_gc()
+// Clean up session ID created by session_start()
 session_destroy();
 ?>
 ]]>
-    </programlisting>
-   </example>
-   <example>
-    <title><function>session_gc</function> example for user accessible script</title>
-    <programlisting role="php">
+   </programlisting>
+  </example>
+  <example>
+   <title><function>session_gc</function> example for user accessible script</title>
+   <programlisting role="php">
 <![CDATA[
 <?php
-// Note: session_gc() is recommended to be used by task manager script, but
+// Note: session_gc() is recommended to be used by a task manager script, but
 // it may be used as follows.
 
 // Used for last GC time check
@@ -97,20 +107,17 @@ if (file_exists($gc_time)) {
 }
 ?>
 ]]>
-    </programlisting>
-   </example>
-  </para>
+   </programlisting>
+  </example>
  </refsect1>
 
  <refsect1 role="seealso">
   &reftitle.seealso;
-  <para>
-   <simplelist>
-    <member><function>session_start</function></member>
-    <member><function>session_destroy</function></member>
-    <member><link linkend="ini.session.gc-probability">session.gc_probability</link></member>
-   </simplelist>
-  </para>
+  <simplelist>
+   <member><function>session_start</function></member>
+   <member><function>session_destroy</function></member>
+   <member><link linkend="ini.session.gc-probability">session.gc_probability</link></member>
+  </simplelist>
  </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file