Improve session_gc documentation #4970

jbafford · 2025-11-01T19:17:52Z

Improve wording of the main body and return values sections
Minor updates to comments in the examples
Incorporate permissions note from PR session_gc: Add note regarding session.save_path and file access / permissions #4915

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

TimWolla · 2025-11-01T19:50:12Z

reference/session/functions/session-gc.xml

-   to 0.
+   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 0


Suggested change

<link linkend="ini.session.gc-probability">session.gc_probability</link> to 0

<link linkend="ini.session.gc-probability">session.gc_probability</link> to <literal>0</literal>

Girgias

Some nits but mostly LGTM

Girgias · 2025-11-01T19:52:15Z

reference/session/functions/session-gc.xml

  </para>
+
+  <note>


CI: failure

Suggested change

</para>

<note>

</para>

<note>

Girgias · 2025-11-01T19:52:53Z

reference/session/functions/session-gc.xml

  <para>
-   <function>session_gc</function> is used to perform session data
-   GC (garbage collection). PHP does probability based session GC by
-   default.
+   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:
  </para>


While at it might as well improve the tags.

Suggested change

<para>

<function>session_gc</function> is used to perform session data

GC (garbage collection). PHP does probability based session GC by

default.

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:

</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>

Girgias · 2025-11-01T19:53:07Z

reference/session/functions/session-gc.xml

+   <para>
+    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.
+   </para>


Suggested change

<para>

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.

</para>

<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>

Girgias · 2025-11-01T19:53:22Z

reference/session/functions/session-gc.xml

  <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.
+   <function>session_gc</function> returns the number of deleted session
+   entries on success, &false; for failure.
  </para>


Suggested change

<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.

<function>session_gc</function> returns the number of deleted session

entries on success, &false; for failure.

</para>

<simpara>

<function>session_gc</function> returns the number of deleted session

entries on success, &return.falseforfailure;.

</simpara>

Girgias · 2025-11-01T19:53:31Z

reference/session/functions/session-gc.xml

+   <para>
+    Old session save handlers do not return number of deleted session data, but 
+    rather only a success/failure flag. If this is the case, 1 is returned regardless of
+    how many session entries are actually deleted.
+   </para>


Suggested change

<para>

Old session save handlers do not return number of deleted session data, but

rather only a success/failure flag. If this is the case, 1 is returned regardless of

how many session entries are actually deleted.

</para>

<simpara>

Old session save handlers do not return number of deleted session data, but

rather only a success/failure flag. If this is the case, 1 is returned regardless of

how many session entries are actually deleted.

</simpara>

Girgias · 2025-11-01T19:55:41Z

reference/session/functions/session-gc.xml

  <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.
+   <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>
  </para>


The para tag is not needed.

Suggested change

<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.

<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>

</para>

<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>

Unless you want it to be part of the previous sentence in the markup, then move it into it and keep the <para> tag rather than replacing them with <simpara>.

* replace para with simpara * add literal tags * Fix CI whitespace issue

Girgias · 2025-11-02T02:39:36Z

reference/session/functions/session-gc.xml

  &reftitle.examples;
-  <para>
+  <simpara>
   <example>
    <title><function>session_gc</function> example for task managers like cron</title>


So this para tag is actually not needed at all

Girgias · 2025-11-02T02:39:58Z

reference/session/functions/session-gc.xml

-  <para>
+  <simpara>
   <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>
+  </simpara>


Ditto: the para tag is not actually needed, just have the simplelist directly.

Girgias · 2025-11-02T02:40:45Z

reference/session/functions/session-gc.xml

+  </simpara>
+
+  <note>


CI: whitespace fix

Suggested change

</simpara>

<note>

</simpara>

<note>

Improve session_gc documentation

1d831a7

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

AllenJB mentioned this pull request Nov 1, 2025

session_gc: Add note regarding session.save_path and file access / permissions #4915

Closed

TimWolla reviewed Nov 1, 2025

View reviewed changes

Girgias reviewed Nov 1, 2025

View reviewed changes

Style updates

bba242d

* replace para with simpara * add literal tags * Fix CI whitespace issue

Girgias reviewed Nov 2, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Improve session_gc documentation #4970

Improve session_gc documentation #4970

Uh oh!

jbafford commented Nov 1, 2025

Uh oh!

TimWolla Nov 1, 2025

Uh oh!

Girgias left a comment

Uh oh!

Girgias Nov 1, 2025 •

edited

Loading

Uh oh!

Girgias Nov 1, 2025

Uh oh!

Girgias Nov 1, 2025

Uh oh!

Girgias Nov 1, 2025

Uh oh!

Girgias Nov 1, 2025

Uh oh!

Girgias Nov 1, 2025

Uh oh!

Girgias Nov 2, 2025

Uh oh!

Girgias Nov 2, 2025

Uh oh!

Girgias Nov 2, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	<link linkend="ini.session.gc-probability">session.gc_probability</link> to 0
	<link linkend="ini.session.gc-probability">session.gc_probability</link> to <literal>0</literal>

-  </para>
-  <note>
+ </para>
+  <note>

Improve session_gc documentation #4970

Are you sure you want to change the base?

Improve session_gc documentation #4970

Uh oh!

Conversation

jbafford commented Nov 1, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Girgias left a comment

Choose a reason for hiding this comment

Uh oh!

Girgias Nov 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Girgias Nov 1, 2025 •

edited

Loading