[DOC-CVS] [doc-en] master: Audit review (#4797)

Author: Gina Peter Banyard (Girgias)
Committer: GitHub (web-flow)
Pusher: bukka
Date: 2025-08-12T23:00:40+02:00

Commit: https://github.com/php/doc-en/commit/bce2cb849721c70737eb32ce958131e22677770c
Raw diff: https://github.com/php/doc-en/commit/bce2cb849721c70737eb32ce958131e22677770c.diff

Audit review (#4797)

* Add an appendix for example code in manual

* dio: Fix issue 8 of audit

* intl: Fix issue 67 of audit

* intl: Fix issue 60 & 61 of audit

* intl: Fix issue 55, 56, 57, 58 & 65 of audit

And make example useful

* enchant: Fix issue 41 of audit

Remove calls to deprecated functions

* enchant: Fix issue 38 of audit

Incorrect variable

* enchant: Fix issue 35 of audit

Remove calls to deprecated functions

* enchant: Fix issue 34 of audit

Incorrect variable

* Fix dio_read return check

* Fix issue 1 and 2

---------

Co-authored-by: Jakub Zelenka <[email protected]>

Changed paths:
  A  appendices/examples.xml
  M  reference/dio/functions/dio-tcsetattr.xml
  M  reference/enchant/functions/enchant-broker-request-dict.xml
  M  reference/enchant/functions/enchant-dict-add.xml
  M  reference/enchant/functions/enchant-dict-describe.xml
  M  reference/enchant/functions/enchant-dict-suggest.xml
  M  reference/filter/constants.xml
  M  reference/intl/intlcalendar/fromdatetime.xml
  M  reference/intl/numberformatter/format.xml
  M  reference/intl/numberformatter/get-error-code.xml


Diff:

diff --git a/appendices/examples.xml b/appendices/examples.xml
new file mode 100644
index 000000000000..176da3a6f954
--- /dev/null
+++ b/appendices/examples.xml
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="utf-8"?>
+<appendix xml:id="examples" xmlns="http://docbook.org/ns/docbook">
+ <title>About manual examples</title>
+ <simpara>
+  It should be noted that many examples in the PHP documentation omit error
+  and exception handling for clarity and brevity.
+ </simpara>
+ <simpara>
+  This does not mean that error handling should be omitted for production code
+  as it can lead to <exceptionname>TypeError</exceptionname>s being thrown,
+  failure values being coerces, such as &false; into an empty string,
+  or assumptions being violated which might cause difficult to track bugs.
+  Some extensions provide complete examples where error handling is included
+  to demonstrate correct usage of the various functions and methods provided
+  by the extension.
+ </simpara>
+</appendix>
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/dio/functions/dio-tcsetattr.xml b/reference/dio/functions/dio-tcsetattr.xml
index a18c2ab29bd9..967dafb8d97b 100644
--- a/reference/dio/functions/dio-tcsetattr.xml
+++ b/reference/dio/functions/dio-tcsetattr.xml
@@ -73,10 +73,9 @@
  </refsect1>
  <refsect1 role="examples">
   &reftitle.examples;
-  <para>
-   <example>
-    <title>Setting the baud rate on a serial port</title>
-    <programlisting role="php">
+  <example>
+   <title>Setting the baud rate on a serial port</title>
+   <programlisting role="php">
 <![CDATA[
 <?php
 
@@ -85,26 +84,23 @@ $fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);
 dio_fcntl($fd, F_SETFL, O_SYNC);
 
 dio_tcsetattr($fd, array(
-  'baud' => 9600,
-  'bits' => 8,
-  'stop'  => 1,
-  'parity' => 0
+    'baud' => 9600,
+    'bits' => 8,
+    'stop'  => 1,
+    'parity' => 0
 )); 
 
-while (1) {
-
-  $data = dio_read($fd, 256);
-
-  if ($data) {
-      echo $data;
-  }
+while (true) {
+    $data = dio_read($fd, 256);
+    if ($data !== null && $date !== '') {
+        echo $data;
+    }
 } 
 
 ?>
 ]]>
-    </programlisting>
-   </example>
-  </para>
+   </programlisting>
+  </example>
  </refsect1>
 
  <refsect1 role="notes">
@@ -112,7 +108,6 @@ while (1) {
   &note.no-windows;
  </refsect1>
 </refentry>
-
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
diff --git a/reference/enchant/functions/enchant-broker-request-dict.xml b/reference/enchant/functions/enchant-broker-request-dict.xml
index d3edfdbff2c9..bf7cf81f8feb 100644
--- a/reference/enchant/functions/enchant-broker-request-dict.xml
+++ b/reference/enchant/functions/enchant-broker-request-dict.xml
@@ -57,7 +57,7 @@
       <entry>8.0.0</entry>
       <entry>
        On success, this function returns an <classname>EnchantDictionary</classname> instance now;
-       previoulsy, a &resource; was retured.
+       previously, a &resource; was returned.
       </entry>
      </row>
     </tbody>
@@ -67,29 +67,27 @@
 
  <refsect1 role="examples">
   &reftitle.examples;
-  <para>
-   <example>
-    <title>A <function>enchant_broker_request_dict</function> example</title>
-    <para>
-     Check if a dictionary exists using
-     <function>enchant_broker_dict_exists</function> and request it.
-    </para>
-    <programlisting role="php">
+  <example>
+   <title>A <function>enchant_broker_request_dict</function> example</title>
+   <para>
+    Check if a dictionary exists using
+    <function>enchant_broker_dict_exists</function> and request it.
+   </para>
+   <programlisting role="php">
 <![CDATA[
 <?php
 $tag = 'en_US';
 $broker = enchant_broker_init();
 if (enchant_broker_dict_exists($broker,$tag)) {
-    $dict = enchant_broker_request_dict($r, $tag);
+    $dict = enchant_broker_request_dict($broker, $tag);
+    var_dump($dict);
 }
 ?>
 ]]>
-    </programlisting>
-   </example>
-  </para>
+   </programlisting>
+  </example>
  </refsect1>
 
-
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
diff --git a/reference/enchant/functions/enchant-dict-add.xml b/reference/enchant/functions/enchant-dict-add.xml
index 9b1f4fadc930..db82c696c7e6 100644
--- a/reference/enchant/functions/enchant-dict-add.xml
+++ b/reference/enchant/functions/enchant-dict-add.xml
@@ -72,8 +72,6 @@ $dict = enchant_broker_request_pwl_dict($broker, $filename);
 
 enchant_dict_add($dict, $word);
 
-enchant_broker_free($broker);
-
 ?>
 ]]>
    </programlisting>
diff --git a/reference/enchant/functions/enchant-dict-describe.xml b/reference/enchant/functions/enchant-dict-describe.xml
index bc5ba2f7769e..71594da27ee9 100644
--- a/reference/enchant/functions/enchant-dict-describe.xml
+++ b/reference/enchant/functions/enchant-dict-describe.xml
@@ -57,28 +57,27 @@
 
  <refsect1 role="examples">
   &reftitle.examples;
-  <para>
-   <example>
-    <title>A <function>enchant_dict_describe</function> example</title>
-    <para>
-     Check if a dictionary exists using
-     <function>enchant_broker_dict_exists</function> and show the detail of it.
-    </para>
-    <programlisting role="php">
+  <example>
+   <title>A <function>enchant_dict_describe</function> example</title>
+   <para>
+    Check if a dictionary exists using
+    <function>enchant_broker_dict_exists</function> and show the detail of it.
+   </para>
+   <programlisting role="php">
 <![CDATA[
 <?php
 $tag = 'en_US';
 $broker = enchant_broker_init();
-if (enchant_broker_dict_exists($broker,$tag)) {
-    $dict = enchant_broker_request_dict($r, $tag);
+if (enchant_broker_dict_exists($broker, $tag)) {
+    $dict = enchant_broker_request_dict($broker, $tag);
     $dict_details = enchant_dict_describe($dict);
     print_r($dict_details);
 }
 ?>
 ]]>
-    </programlisting>
-    &example.outputs.similar;
-    <screen>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
 <![CDATA[
 Array
 (
@@ -88,25 +87,9 @@ Array
     [file] => /usr/lib/enchant/libenchant_aspell.so
 )
 ]]>
-    </screen>
-   </example>
-  </para>
+   </screen>
+  </example>
  </refsect1>
-
-
- <!-- Use when adding See Also links
- <refsect1 role="seealso">
-  &reftitle.seealso;
-  <para>
-   <simplelist>
-    <member><function></function></member>
-    <member>Or <link linkend="somethingelse">something else</link></member>
-   </simplelist>
-  </para>
- </refsect1>
- -->
-
-
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/enchant/functions/enchant-dict-suggest.xml b/reference/enchant/functions/enchant-dict-suggest.xml
index a7cb731efa72..d1c20a12a927 100644
--- a/reference/enchant/functions/enchant-dict-suggest.xml
+++ b/reference/enchant/functions/enchant-dict-suggest.xml
@@ -58,10 +58,9 @@
 
  <refsect1 role="examples">
   &reftitle.examples;
-  <para>
-   <example>
-    <title>A <function>enchant_dict_suggest</function> example</title>
-    <programlisting role="php">
+  <example>
+   <title>A <function>enchant_dict_suggest</function> example</title>
+   <programlisting role="php">
 <![CDATA[
 <?php
 $tag = 'en_US';
@@ -75,14 +74,11 @@ if (enchant_broker_dict_exists($r,$tag)) {
         echo "Suggestions for 'soong':";
         print_r($suggs);
     }
-    enchant_broker_free_dict($d);
 }
-enchant_broker_free($r);
 ?>
 ]]>
-    </programlisting>
-   </example>
-  </para>
+   </programlisting>
+  </example>
  </refsect1>
 
  <refsect1 role="seealso">
diff --git a/reference/filter/constants.xml b/reference/filter/constants.xml
index f8efbc490f15..20e5c9ba7691 100644
--- a/reference/filter/constants.xml
+++ b/reference/filter/constants.xml
@@ -1183,7 +1183,7 @@ string(5) "12.34"
      <programlisting role="php">
 <![CDATA[
 <?php
-function validate_login($value): ?string
+function validate_login(string $value): ?string
 {
     if (strlen($value) >= 5 && ctype_alnum($value)) {
         return $value;
diff --git a/reference/intl/intlcalendar/fromdatetime.xml b/reference/intl/intlcalendar/fromdatetime.xml
index f05e174f1672..7cc4917f5a40 100644
--- a/reference/intl/intlcalendar/fromdatetime.xml
+++ b/reference/intl/intlcalendar/fromdatetime.xml
@@ -74,7 +74,7 @@
 ini_set('date.timezone', 'Europe/Lisbon');
 
 //same as IntlCalendar::fromDateTime(new DateTime(...))
-$cal1 = IntlCalendar::fromDateTime('2013-02-28 00:01:02 Europe/Berlin');
+$cal1 = IntlCalendar::fromDateTime('2013-02-28 00:01:02 Europe/Berlin', 'de_DE');
 
 //Note the timezone is Europe/Berlin, not the default Europe/Lisbon
 echo IntlDateFormatter::formatObject($cal1, 'yyyy MMMM d HH:mm:ss VVVV', 'de_DE'), "\n";
diff --git a/reference/intl/numberformatter/format.xml b/reference/intl/numberformatter/format.xml
index 585718719338..a6bbe17e1c20 100644
--- a/reference/intl/numberformatter/format.xml
+++ b/reference/intl/numberformatter/format.xml
@@ -85,9 +85,7 @@
 <?php
 $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
 $data = numfmt_format($fmt, 1234567.891234567890000);
-if(intl_is_failure(numfmt_format($fmt))) {
-    report_error("Formatter error");
-}
+var_dump($data);
 ?>
 ]]>
    </programlisting>
@@ -98,10 +96,8 @@ if(intl_is_failure(numfmt_format($fmt))) {
 <![CDATA[
 <?php
 $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
-$fmt->format(1234567.891234567890000);
-if(intl_is_failure($fmt->getErrorCode())) {
-    report_error("Formatter error");
-}
+$data = $fmt->format(1234567.891234567890000);
+var_dump($data);
 ?>
 ]]>
    </programlisting>
@@ -109,7 +105,7 @@ if(intl_is_failure($fmt->getErrorCode())) {
   &example.outputs;
   <screen>
 <![CDATA[
-1.234.567,891
+string(13) "1.234.567,891"
 ]]>
   </screen>
  </refsect1>
diff --git a/reference/intl/numberformatter/get-error-code.xml b/reference/intl/numberformatter/get-error-code.xml
index 7541eaeb503b..afcdd2f734cb 100644
--- a/reference/intl/numberformatter/get-error-code.xml
+++ b/reference/intl/numberformatter/get-error-code.xml
@@ -61,8 +61,8 @@
 <?php
 $fmt  = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
 $data = numfmt_format($fmt, 1234567.891234567890000);
-if(intl_is_failure(numfmt_get_error_code($fmt))) {
-    report_error("Formatter error");
+if (intl_is_failure(numfmt_get_error_code($fmt))) {
+    echo 'Formatter error';
 }
 ?>
 ]]>
@@ -75,8 +75,8 @@ if(intl_is_failure(numfmt_get_error_code($fmt))) {
 <?php
 $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
 $fmt->format(1234567.891234567890000);
-if(intl_is_failure($fmt->getErrorCode())) {
-    report_error("Formatter error");
+if (intl_is_failure($fmt->getErrorCode())) {
+    echo 'Formatter error';
 }
 ?>
 ]]>