[doc-en] master: readline: Document functions unavailable where feature is not supported (#4923)

From: Date: Tue, 01 Sep 2026 14:39:24 +0000
Subject: [doc-en] master: readline: Document functions unavailable where feature is not supported (#4923)
Groups: php.doc.cvs 
Request: Send a blank email to doc-cvs+get-23690@lists.php.net to get a copy of this message
Author: AllenJB (AllenJB) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-09-01T16:39:20+02:00 Commit: https://github.com/php/doc-en/commit/8648d1cda141537b5dbd403a0bf0e6eb8c086e9d Raw diff: https://github.com/php/doc-en/commit/8648d1cda141537b5dbd403a0bf0e6eb8c086e9d.diff readline: Document functions unavailable where feature is not supported (#4923) * readline: Document functions unavailable where feature is not supported (fixes #1482) * Move callback feature system support notice to an entity * readline: Document functions unavailable where feature is not supported (fixes #1482) * readline: reconcile the Windows availability statements The extension is supported on Windows, but five of its functions are not present in that build. Say so where the extension-level statement is made, list the affected functions in the requirements section, and point at function_exists() and READLINE_LIB so a reader can test their own build. Changed paths: M language-snippets.ent M reference/readline/book.xml M reference/readline/functions/readline-callback-handler-install.xml M reference/readline/functions/readline-callback-handler-remove.xml M reference/readline/functions/readline-callback-read-char.xml M reference/readline/functions/readline-list-history.xml M reference/readline/functions/readline-on-new-line.xml M reference/readline/functions/readline-redisplay.xml M reference/readline/setup.xml Diff: diff --git a/language-snippets.ent b/language-snippets.ent index 11856a0efe2f..d98bb6831217 100644 --- a/language-snippets.ent +++ b/language-snippets.ent @@ -4572,6 +4572,14 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been </informaltable> '> +<!-- readline --> +<!ENTITY readline.system-callback-support ' + <simpara xmlns="http://docbook.org/ns/docbook"> + This function is only available if the readline library PHP was built + against supports it. It is not available on Windows. + </simpara> +'> + <!-- Keep this comment at the end of the file Local variables: mode: sgml diff --git a/reference/readline/book.xml b/reference/readline/book.xml index 2eb6b58dbcc2..59785a9cf9ac 100644 --- a/reference/readline/book.xml +++ b/reference/readline/book.xml @@ -19,7 +19,9 @@ <link linkend="features.commandline">command line</link>. </simpara> <simpara> - As of PHP 7.1.0 this extension is supported on Windows. + As of PHP 7.1.0 this extension is supported on Windows, where it is built + against libedit. Not every function is present in that build; see + <link linkend="readline.requirements">the requirements</link>. </simpara> <caution> <simpara> diff --git a/reference/readline/functions/readline-callback-handler-install.xml b/reference/readline/functions/readline-callback-handler-install.xml index 2fa3d1e1d48b..82ef06a3c6a1 100644 --- a/reference/readline/functions/readline-callback-handler-install.xml +++ b/reference/readline/functions/readline-callback-handler-install.xml @@ -25,6 +25,7 @@ <function>stream_select</function> as it allows interleaving of IO and user input, unlike <function>readline</function>. </simpara> + &readline.system-callback-support; </refsect1> <refsect1 role="parameters"> diff --git a/reference/readline/functions/readline-callback-handler-remove.xml b/reference/readline/functions/readline-callback-handler-remove.xml index 26a3f6664462..fc0c1bfd6cc6 100644 --- a/reference/readline/functions/readline-callback-handler-remove.xml +++ b/reference/readline/functions/readline-callback-handler-remove.xml @@ -16,6 +16,7 @@ Removes a previously installed callback handler and restores terminal settings. </simpara> + &readline.system-callback-support; </refsect1> <refsect1 role="parameters"> diff --git a/reference/readline/functions/readline-callback-read-char.xml b/reference/readline/functions/readline-callback-read-char.xml index 890c3d989e4f..8d1eb68cb586 100644 --- a/reference/readline/functions/readline-callback-read-char.xml +++ b/reference/readline/functions/readline-callback-read-char.xml @@ -18,6 +18,7 @@ <function>readline_callback_handler_install</function> that a line is ready for input. </simpara> + &readline.system-callback-support; </refsect1> <refsect1 role="parameters"> diff --git a/reference/readline/functions/readline-list-history.xml b/reference/readline/functions/readline-list-history.xml index 9c901ef9d863..bf090328eb0a 100644 --- a/reference/readline/functions/readline-list-history.xml +++ b/reference/readline/functions/readline-list-history.xml @@ -15,6 +15,11 @@ <simpara> Gets the entire command line history. </simpara> + <simpara> + This function is only available if the readline library PHP was built + against provides history listing. This is always the case with GNU Readline + and on Windows. + </simpara> </refsect1> <refsect1 role="parameters"> diff --git a/reference/readline/functions/readline-on-new-line.xml b/reference/readline/functions/readline-on-new-line.xml index b45bfae13a96..00d80ef3f97b 100644 --- a/reference/readline/functions/readline-on-new-line.xml +++ b/reference/readline/functions/readline-on-new-line.xml @@ -15,6 +15,7 @@ <simpara> Tells readline that the cursor has moved to a new line. </simpara> + &readline.system-callback-support; </refsect1> <refsect1 role="parameters"> @@ -29,14 +30,11 @@ </simpara> </refsect1> - <refsect1 role="notes"> - &reftitle.notes; - <note> - <simpara> - This function is only available if supported by the underlying readline library. - It is not supported on Windows. - </simpara> - </note> + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><function>readline_callback_handler_install</function></member> + </simplelist> </refsect1> </refentry> <!-- Keep this comment at the end of the file diff --git a/reference/readline/functions/readline-redisplay.xml b/reference/readline/functions/readline-redisplay.xml index 330cbdfea91d..dd3ceaf489ea 100644 --- a/reference/readline/functions/readline-redisplay.xml +++ b/reference/readline/functions/readline-redisplay.xml @@ -15,6 +15,7 @@ <simpara> Redraws readline to redraw the display. </simpara> + &readline.system-callback-support; </refsect1> <refsect1 role="parameters"> @@ -28,6 +29,13 @@ &return.void; </simpara> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><function>readline_callback_handler_install</function></member> + </simplelist> + </refsect1> </refentry> <!-- Keep this comment at the end of the file Local variables: diff --git a/reference/readline/setup.xml b/reference/readline/setup.xml index cb48466f8ead..3775e54f8334 100644 --- a/reference/readline/setup.xml +++ b/reference/readline/setup.xml @@ -18,6 +18,19 @@ licensed and available for download from <link xlink:href="&url.libedit;">&url.libedit;</link>. </simpara> + <simpara> + The two libraries do not provide the same features, so some functions are + absent from some builds. The functions driving the callback interface, + <function>readline_callback_handler_install</function>, + <function>readline_callback_handler_remove</function>, + <function>readline_callback_read_char</function>, + <function>readline_redisplay</function> and + <function>readline_on_new_line</function>, are only present when the + underlying library provides them, and are absent on Windows. Calling an + absent function throws an <exceptionname>Error</exceptionname>. + <function>function_exists</function> tests for a given function, and the + <constant>READLINE_LIB</constant> constant reports which library is in use. + </simpara> </section> <!-- }}} -->

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