[doc-en] master: Fix session read handler docs: false reports a failure, not a missing session (#5902)

Author: Eric Stern (Firehed) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-10-01T08:33:48+02:00 Commit: https://github.com/php/doc-en/commit/38bdb42b928616a559444a29fb5ae41f150fec59 Raw diff: https://github.com/php/doc-en/commit/38bdb42b928616a559444a29fb5ae41f150fec59.diff Fix session read handler docs: false reports a failure, not a missing session (#5902) Changed paths: M reference/session/functions/session-set-save-handler.xml M reference/session/sessionhandler/read.xml M reference/session/sessionhandlerinterface/read.xml Diff: diff --git a/reference/session/functions/session-set-save-handler.xml b/reference/session/functions/session-set-save-handler.xml index 7c00c2d8ae65..105af55df3c4 100644 --- a/reference/session/functions/session-set-save-handler.xml +++ b/reference/session/functions/session-set-save-handler.xml @@ -112,14 +112,16 @@ <para> A callable with the following signature: <methodsynopsis> - <type>string</type><methodname><replaceable>read</replaceable></methodname> + <type class="union"><type>string</type><type>false</type></type><methodname><replaceable>read</replaceable></methodname> <methodparam><type>string</type><parameter>sessionId</parameter></methodparam> </methodsynopsis> </para> - <para> + <simpara> The <parameter>read</parameter> callback must always return a session encoded (serialized) string, or an empty string if there is no data to read. - </para> + It must return &false; to report a failure: + <function>session_start</function> then emits an <constant>E_WARNING</constant> and returns &false;. + </simpara> <para> This callback is called internally by PHP when the session starts or when <function>session_start</function> is called. Before this callback is invoked diff --git a/reference/session/sessionhandler/read.xml b/reference/session/sessionhandler/read.xml index e466519148cb..567311071876 100644 --- a/reference/session/sessionhandler/read.xml +++ b/reference/session/sessionhandler/read.xml @@ -51,9 +51,12 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para> - Returns an encoded string of the read data. If nothing was read, it must return &false;. Note this value is returned internally to PHP for processing. - </para> + <simpara> + Returns the encoded session data from the internal save handler, + an empty string if it holds no data for the session ID, + or &false; if the internal save handler failed to read. + Note this value is returned internally to PHP for processing. + </simpara> </refsect1> <refsect1 role="seealso"> diff --git a/reference/session/sessionhandlerinterface/read.xml b/reference/session/sessionhandlerinterface/read.xml index 494fe63aafd8..57fa36268297 100644 --- a/reference/session/sessionhandlerinterface/read.xml +++ b/reference/session/sessionhandlerinterface/read.xml @@ -17,13 +17,14 @@ Called right after the session starts or when <function>session_start</function> is called. Please note that before this method is called <function>SessionHandlerInterface::open</function> is invoked. </para> - <para> + <simpara> This method is called by PHP itself when the session is started. This method should retrieve the session data from storage by the session ID provided. The string returned by this method must be in the same - serialized format as when originally passed to the <function>SessionHandlerInterface::write</function> - If the record was not found, return &false;. - </para> + serialized format as when originally passed to the <function>SessionHandlerInterface::write</function>. + Return an empty string when no data is stored for the given session ID; + return &false; only to report a failure. + </simpara> <para> The data returned by this method will be decoded internally by PHP using the unserialization method specified in <link linkend="ini.session.serialize-handler">session.serialize_handler</link>. @@ -51,9 +52,13 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para> - Returns an encoded string of the read data. If nothing was read, it must return &false;. Note this value is returned internally to PHP for processing. - </para> + <simpara> + Returns an encoded string of the read data, + or an empty string if no data is stored for the session ID. + Returning &false; reports a failure: + <function>session_start</function> then emits an <constant>E_WARNING</constant> and returns &false;. + Note this value is returned internally to PHP for processing. + </simpara> </refsect1> <refsect1 role="seealso">