Skip to content

Commit bce2cb8

Browse files
Girgiasbukka
Girgias
and
bukka
authored
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]>
1 parent 1bcc40f commit bce2cb8

File tree

10 files changed

+92
-89
lines changed

10 files changed

+92
-89
lines changed

‎appendices/examples.xml

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<appendix xml:id="examples" xmlns="http://docbook.org/ns/docbook">
3+
<title>About manual examples</title>
4+
<simpara>
5+
It should be noted that many examples in the PHP documentation omit error
6+
and exception handling for clarity and brevity.
7+
</simpara>
8+
<simpara>
9+
This does not mean that error handling should be omitted for production code
10+
as it can lead to <exceptionname>TypeError</exceptionname>s being thrown,
11+
failure values being coerces, such as &false; into an empty string,
12+
or assumptions being violated which might cause difficult to track bugs.
13+
Some extensions provide complete examples where error handling is included
14+
to demonstrate correct usage of the various functions and methods provided
15+
by the extension.
16+
</simpara>
17+
</appendix>
18+
<!-- Keep this comment at the end of the file
19+
Local variables:
20+
mode: sgml
21+
sgml-omittag:t
22+
sgml-shorttag:t
23+
sgml-minimize-attributes:nil
24+
sgml-always-quote-attributes:t
25+
sgml-indent-step:1
26+
sgml-indent-data:t
27+
indent-tabs-mode:nil
28+
sgml-parent-document:nil
29+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
30+
sgml-exposed-tags:nil
31+
sgml-local-catalogs:nil
32+
sgml-local-ecat-files:nil
33+
End:
34+
vim600: syn=xml fen fdm=syntax fdl=2 si
35+
vim: et tw=78 syn=sgml
36+
vi: ts=1 sw=1
37+
-->

‎reference/dio/functions/dio-tcsetattr.xml

Lines changed: 14 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -73,10 +73,9 @@
7373
</refsect1>
7474
<refsect1 role="examples">
7575
&reftitle.examples;
76-
<para>
77-
<example>
78-
<title>Setting the baud rate on a serial port</title>
79-
<programlisting role="php">
76+
<example>
77+
<title>Setting the baud rate on a serial port</title>
78+
<programlisting role="php">
8079
<![CDATA[
8180
<?php
8281
@@ -85,34 +84,30 @@ $fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);
8584
dio_fcntl($fd, F_SETFL, O_SYNC);
8685
8786
dio_tcsetattr($fd, array(
88-
'baud' => 9600,
89-
'bits' => 8,
90-
'stop' => 1,
91-
'parity' => 0
87+
'baud' => 9600,
88+
'bits' => 8,
89+
'stop' => 1,
90+
'parity' => 0
9291
));
9392
94-
while (1) {
95-
96-
$data = dio_read($fd, 256);
97-
98-
if ($data) {
99-
echo $data;
100-
}
93+
while (true) {
94+
$data = dio_read($fd, 256);
95+
if ($data !== null && $date !== '') {
96+
echo $data;
97+
}
10198
}
10299
103100
?>
104101
]]>
105-
</programlisting>
106-
</example>
107-
</para>
102+
</programlisting>
103+
</example>
108104
</refsect1>
109105

110106
<refsect1 role="notes">
111107
&reftitle.notes;
112108
&note.no-windows;
113109
</refsect1>
114110
</refentry>
115-
116111
<!-- Keep this comment at the end of the file
117112
Local variables:
118113
mode: sgml

‎reference/enchant/functions/enchant-broker-request-dict.xml

Lines changed: 12 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@
5757
<entry>8.0.0</entry>
5858
<entry>
5959
On success, this function returns an <classname>EnchantDictionary</classname> instance now;
60-
previoulsy, a &resource; was retured.
60+
previously, a &resource; was returned.
6161
</entry>
6262
</row>
6363
</tbody>
@@ -67,29 +67,27 @@
6767

6868
<refsect1 role="examples">
6969
&reftitle.examples;
70-
<para>
71-
<example>
72-
<title>A <function>enchant_broker_request_dict</function> example</title>
73-
<para>
74-
Check if a dictionary exists using
75-
<function>enchant_broker_dict_exists</function> and request it.
76-
</para>
77-
<programlisting role="php">
70+
<example>
71+
<title>A <function>enchant_broker_request_dict</function> example</title>
72+
<para>
73+
Check if a dictionary exists using
74+
<function>enchant_broker_dict_exists</function> and request it.
75+
</para>
76+
<programlisting role="php">
7877
<![CDATA[
7978
<?php
8079
$tag = 'en_US';
8180
$broker = enchant_broker_init();
8281
if (enchant_broker_dict_exists($broker,$tag)) {
83-
$dict = enchant_broker_request_dict($r, $tag);
82+
$dict = enchant_broker_request_dict($broker, $tag);
83+
var_dump($dict);
8484
}
8585
?>
8686
]]>
87-
</programlisting>
88-
</example>
89-
</para>
87+
</programlisting>
88+
</example>
9089
</refsect1>
9190

92-
9391
<refsect1 role="seealso">
9492
&reftitle.seealso;
9593
<para>

‎reference/enchant/functions/enchant-dict-add.xml

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,8 +72,6 @@ $dict = enchant_broker_request_pwl_dict($broker, $filename);
7272
7373
enchant_dict_add($dict, $word);
7474
75-
enchant_broker_free($broker);
76-
7775
?>
7876
]]>
7977
</programlisting>

‎reference/enchant/functions/enchant-dict-describe.xml

Lines changed: 14 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -57,28 +57,27 @@
5757

5858
<refsect1 role="examples">
5959
&reftitle.examples;
60-
<para>
61-
<example>
62-
<title>A <function>enchant_dict_describe</function> example</title>
63-
<para>
64-
Check if a dictionary exists using
65-
<function>enchant_broker_dict_exists</function> and show the detail of it.
66-
</para>
67-
<programlisting role="php">
60+
<example>
61+
<title>A <function>enchant_dict_describe</function> example</title>
62+
<para>
63+
Check if a dictionary exists using
64+
<function>enchant_broker_dict_exists</function> and show the detail of it.
65+
</para>
66+
<programlisting role="php">
6867
<![CDATA[
6968
<?php
7069
$tag = 'en_US';
7170
$broker = enchant_broker_init();
72-
if (enchant_broker_dict_exists($broker,$tag)) {
73-
$dict = enchant_broker_request_dict($r, $tag);
71+
if (enchant_broker_dict_exists($broker, $tag)) {
72+
$dict = enchant_broker_request_dict($broker, $tag);
7473
$dict_details = enchant_dict_describe($dict);
7574
print_r($dict_details);
7675
}
7776
?>
7877
]]>
79-
</programlisting>
80-
&example.outputs.similar;
81-
<screen>
78+
</programlisting>
79+
&example.outputs.similar;
80+
<screen>
8281
<![CDATA[
8382
Array
8483
(
@@ -88,25 +87,9 @@ Array
8887
[file] => /usr/lib/enchant/libenchant_aspell.so
8988
)
9089
]]>
91-
</screen>
92-
</example>
93-
</para>
90+
</screen>
91+
</example>
9492
</refsect1>
95-
96-
97-
<!-- Use when adding See Also links
98-
<refsect1 role="seealso">
99-
&reftitle.seealso;
100-
<para>
101-
<simplelist>
102-
<member><function></function></member>
103-
<member>Or <link linkend="somethingelse">something else</link></member>
104-
</simplelist>
105-
</para>
106-
</refsect1>
107-
-->
108-
109-
11093
</refentry>
11194
<!-- Keep this comment at the end of the file
11295
Local variables:

‎reference/enchant/functions/enchant-dict-suggest.xml

Lines changed: 5 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -58,10 +58,9 @@
5858

5959
<refsect1 role="examples">
6060
&reftitle.examples;
61-
<para>
62-
<example>
63-
<title>A <function>enchant_dict_suggest</function> example</title>
64-
<programlisting role="php">
61+
<example>
62+
<title>A <function>enchant_dict_suggest</function> example</title>
63+
<programlisting role="php">
6564
<![CDATA[
6665
<?php
6766
$tag = 'en_US';
@@ -75,14 +74,11 @@ if (enchant_broker_dict_exists($r,$tag)) {
7574
echo "Suggestions for 'soong':";
7675
print_r($suggs);
7776
}
78-
enchant_broker_free_dict($d);
7977
}
80-
enchant_broker_free($r);
8178
?>
8279
]]>
83-
</programlisting>
84-
</example>
85-
</para>
80+
</programlisting>
81+
</example>
8682
</refsect1>
8783

8884
<refsect1 role="seealso">

‎reference/filter/constants.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1183,7 +1183,7 @@ string(5) "12.34"
11831183
<programlisting role="php">
11841184
<![CDATA[
11851185
<?php
1186-
function validate_login($value): ?string
1186+
function validate_login(string $value): ?string
11871187
{
11881188
if (strlen($value) >= 5 && ctype_alnum($value)) {
11891189
return $value;

‎reference/intl/intlcalendar/fromdatetime.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@
7474
ini_set('date.timezone', 'Europe/Lisbon');
7575
7676
//same as IntlCalendar::fromDateTime(new DateTime(...))
77-
$cal1 = IntlCalendar::fromDateTime('2013-02-28 00:01:02 Europe/Berlin');
77+
$cal1 = IntlCalendar::fromDateTime('2013-02-28 00:01:02 Europe/Berlin', 'de_DE');
7878
7979
//Note the timezone is Europe/Berlin, not the default Europe/Lisbon
8080
echo IntlDateFormatter::formatObject($cal1, 'yyyy MMMM d HH:mm:ss VVVV', 'de_DE'), "\n";

‎reference/intl/numberformatter/format.xml

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -85,9 +85,7 @@
8585
<?php
8686
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
8787
$data = numfmt_format($fmt, 1234567.891234567890000);
88-
if(intl_is_failure(numfmt_format($fmt))) {
89-
report_error("Formatter error");
90-
}
88+
var_dump($data);
9189
?>
9290
]]>
9391
</programlisting>
@@ -98,18 +96,16 @@ if(intl_is_failure(numfmt_format($fmt))) {
9896
<![CDATA[
9997
<?php
10098
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
101-
$fmt->format(1234567.891234567890000);
102-
if(intl_is_failure($fmt->getErrorCode())) {
103-
report_error("Formatter error");
104-
}
99+
$data = $fmt->format(1234567.891234567890000);
100+
var_dump($data);
105101
?>
106102
]]>
107103
</programlisting>
108104
</example>
109105
&example.outputs;
110106
<screen>
111107
<![CDATA[
112-
1.234.567,891
108+
string(13) "1.234.567,891"
113109
]]>
114110
</screen>
115111
</refsect1>

‎reference/intl/numberformatter/get-error-code.xml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -61,8 +61,8 @@
6161
<?php
6262
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
6363
$data = numfmt_format($fmt, 1234567.891234567890000);
64-
if(intl_is_failure(numfmt_get_error_code($fmt))) {
65-
report_error("Formatter error");
64+
if (intl_is_failure(numfmt_get_error_code($fmt))) {
65+
echo 'Formatter error';
6666
}
6767
?>
6868
]]>
@@ -75,8 +75,8 @@ if(intl_is_failure(numfmt_get_error_code($fmt))) {
7575
<?php
7676
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
7777
$fmt->format(1234567.891234567890000);
78-
if(intl_is_failure($fmt->getErrorCode())) {
79-
report_error("Formatter error");
78+
if (intl_is_failure($fmt->getErrorCode())) {
79+
echo 'Formatter error';
8080
}
8181
?>
8282
]]>

0 commit comments

Comments
 (0)