Skip to content

Commit f808a54

Browse files
GirgiasGirgias
committed
Rework documentation for dir functions
Include 8.5 deprecation for passing null to use the last opened directory.
1 parent 7e384b2 commit f808a54

File tree

4 files changed

+216
-212
lines changed

4 files changed

+216
-212
lines changed

‎reference/dir/functions/closedir.xml‎

Lines changed: 63 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,4 @@
11
<?xml version="1.0" encoding="utf-8"?>
2-
<!-- $Revision$ -->
3-
<!-- splitted from ./en/functions/dir.xml, last change in rev 1.2 -->
42
<refentry xml:id="function.closedir" xmlns="http://docbook.org/ns/docbook">
53
<refnamediv>
64
<refname>closedir</refname>
@@ -13,61 +11,84 @@
1311
<type>void</type><methodname>closedir</methodname>
1412
<methodparam choice="opt"><type class="union"><type>resource</type><type>null</type></type><parameter>dir_handle</parameter><initializer>&null;</initializer></methodparam>
1513
</methodsynopsis>
16-
<para>
14+
<simpara>
1715
Closes the directory stream indicated by
18-
<parameter>dir_handle</parameter>. The stream must have previously
19-
been opened by <function>opendir</function>.
20-
</para>
16+
<parameter>dir_handle</parameter>.
17+
</simpara>
2118
</refsect1>
2219

2320
<refsect1 role="parameters">
2421
&reftitle.parameters;
25-
<para>
26-
<variablelist>
27-
<varlistentry>
28-
<term><parameter>dir_handle</parameter></term>
29-
<listitem>
30-
<para>
31-
The directory handle <type>resource</type> previously opened
32-
with <function>opendir</function>. If the directory handle is
33-
not specified, the last link opened by <function>opendir</function>
34-
is assumed.
35-
</para>
36-
</listitem>
37-
</varlistentry>
38-
</variablelist>
39-
</para>
22+
<variablelist>
23+
<varlistentry>
24+
<term><parameter>dir_handle</parameter></term>
25+
<listitem>
26+
<simpara>
27+
A directory handle <type>resource</type> previously opened
28+
with <function>opendir</function>.
29+
If <parameter>dir_handle</parameter> is &null; the last handle opened
30+
using <function>opendir</function> will be used.
31+
</simpara>
32+
</listitem>
33+
</varlistentry>
34+
</variablelist>
35+
</refsect1>
36+
37+
<refsect1 role="changelog">
38+
&reftitle.changelog;
39+
<informaltable>
40+
<tgroup cols="2">
41+
<thead>
42+
<row>
43+
<entry>&Version;</entry>
44+
<entry>&Description;</entry>
45+
</row>
46+
</thead>
47+
<tbody>
48+
<row>
49+
<entry>8.5.0</entry>
50+
<entry>
51+
Using &null; for <parameter>dir_handle</parameter> is now deprecated.
52+
Instead, the last opened directory handle should be explicitly provided.
53+
</entry>
54+
</row>
55+
<row>
56+
<entry>8.0.0</entry>
57+
<entry>
58+
<parameter>dir_handle</parameter> is now nullable.
59+
</entry>
60+
</row>
61+
</tbody>
62+
</tgroup>
63+
</informaltable>
4064
</refsect1>
4165

4266
<refsect1 role="returnvalues">
4367
&reftitle.returnvalues;
44-
<para>
68+
<simpara>
4569
&return.void;
46-
</para>
70+
</simpara>
4771
</refsect1>
4872

4973
<refsect1 role="examples">
5074
&reftitle.examples;
51-
<para>
52-
<example>
53-
<title><function>closedir</function> example</title>
54-
<programlisting role="php">
55-
<![CDATA[
56-
<?php
57-
$dir = "/etc/php5/";
75+
<simpara>
76+
For a complete example refer to the <function>opendir</function>
77+
documentation.
78+
</simpara>
79+
</refsect1>
5880

59-
// Open a known directory, read directory into variable and then close
60-
if (is_dir($dir)) {
61-
if ($dh = opendir($dir)) {
62-
$directory = readdir($dh);
63-
closedir($dh);
64-
}
65-
}
66-
?>
67-
]]>
68-
</programlisting>
69-
</example>
70-
</para>
81+
<refsect1 role="seealso">
82+
&reftitle.seealso;
83+
<simplelist>
84+
<member><function>opendir</function></member>
85+
<member><function>readdir</function></member>
86+
<member><function>rewinddir</function></member>
87+
<member><function>dir</function></member>
88+
<member><function>is_dir</function></member>
89+
<member><function>glob</function></member>
90+
<member><function>scandir</function></member>
91+
</simplelist>
7192
</refsect1>
7293
</refentry>
7394
<!-- Keep this comment at the end of the file

‎reference/dir/functions/opendir.xml‎

Lines changed: 67 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,4 @@
11
<?xml version="1.0" encoding="utf-8"?>
2-
<!-- $Revision$ -->
3-
<!-- splitted from ./en/functions/dir.xml, last change in rev 1.2 -->
42
<refentry xml:id="function.opendir" xmlns="http://docbook.org/ns/docbook">
53
<refnamediv>
64
<refname>opendir</refname>
@@ -14,55 +12,53 @@
1412
<methodparam><type>string</type><parameter>directory</parameter></methodparam>
1513
<methodparam choice="opt"><type class="union"><type>resource</type><type>null</type></type><parameter>context</parameter><initializer>&null;</initializer></methodparam>
1614
</methodsynopsis>
17-
<para>
15+
<simpara>
1816
Opens up a directory handle to be used in subsequent
1917
<function>closedir</function>, <function>readdir</function>, and
2018
<function>rewinddir</function> calls.
21-
</para>
19+
</simpara>
2220
</refsect1>
2321

2422
<refsect1 role="parameters">
2523
&reftitle.parameters;
26-
<para>
27-
<variablelist>
28-
<varlistentry>
29-
<term><parameter>directory</parameter></term>
30-
<listitem>
31-
<para>
32-
The directory path that is to be opened
33-
</para>
34-
</listitem>
35-
</varlistentry>
36-
<varlistentry>
37-
<term><parameter>context</parameter></term>
38-
<listitem>
39-
<para>
40-
For a description of the <parameter>context</parameter> parameter,
41-
refer to <link linkend="ref.stream">the streams section</link> of
42-
the manual.
43-
</para>
44-
</listitem>
45-
</varlistentry>
46-
</variablelist>
47-
</para>
24+
<variablelist>
25+
<varlistentry>
26+
<term><parameter>directory</parameter></term>
27+
<listitem>
28+
<simpara>
29+
The directory path to open.
30+
</simpara>
31+
</listitem>
32+
</varlistentry>
33+
<varlistentry>
34+
<term><parameter>context</parameter></term>
35+
<listitem>
36+
<para>
37+
For a description of the <parameter>context</parameter> parameter,
38+
refer to <link linkend="ref.stream">the streams section</link> of
39+
the manual.
40+
</para>
41+
</listitem>
42+
</varlistentry>
43+
</variablelist>
4844
</refsect1>
4945

5046
<refsect1 role="returnvalues">
5147
&reftitle.returnvalues;
52-
<para>
53-
Returns a directory handle <type>resource</type> on success,
48+
<simpara>
49+
Returns a directory handle on success,
5450
&return.falseforfailure;
55-
</para>
51+
</simpara>
5652
</refsect1>
5753

5854
<refsect1 role="errors">
5955
&reftitle.errors;
6056
&fs.emits.warning.on.failure;
61-
<para>
57+
<simpara>
6258
This may happen if <parameter>directory</parameter> is not a valid directory,
6359
the directory can not be opened due to permission restrictions,
6460
or due to filesystem errors.
65-
</para>
61+
</simpara>
6662
</refsect1>
6763

6864
<refsect1 role="changelog">
@@ -89,49 +85,65 @@
8985

9086
<refsect1 role="examples">
9187
&reftitle.examples;
92-
<para>
93-
<example>
94-
<title><function>opendir</function> example</title>
95-
<programlisting role="php">
88+
<example>
89+
<title>
90+
List all entries in a directory, skipping the special <literal>.</literal>
91+
and <literal>..</literal> directories
92+
</title>
93+
<simpara>
94+
Because file and directory names can be strings that PHP considers "falsy"
95+
(e.g. a directory named <literal>"0"</literal>) and
96+
<function>readdir</function> returns &false; when it has read all entries
97+
in a directory one needs to use the <literal>===</literal>
98+
<link linkend="language.operators.comparison">comparison operator</link>
99+
to properly distinguish between a directory entry whose name is "falsy"
100+
and having read all entries of the directory.
101+
</simpara>
102+
<programlisting role="php">
96103
<![CDATA[
97104
<?php
98-
$dir = "/etc/php5/";
99105
100-
// Open a known directory, and proceed to read its contents
101-
if (is_dir($dir)) {
102-
if ($dh = opendir($dir)) {
103-
while (($file = readdir($dh)) !== false) {
104-
echo "filename: $file : filetype: " . filetype($dir . $file) . "\n";
106+
if ($handle = opendir('/path/to/files')) {
107+
echo "Directory handle: $handle\n";
108+
echo "Entries:\n";
109+
110+
/* Correctly handling directory entries that may be considered falsy */
111+
while (false !== ($entry = readdir($handle))) {
112+
if ($entry === '.' || $entry === '..') {
113+
continue;
105114
}
106-
closedir($dh);
115+
echo "$entry\n";
107116
}
117+
118+
closedir($handle);
108119
}
109120
?>
110121
]]>
111-
</programlisting>
112-
&example.outputs.similar;
113-
<screen>
122+
</programlisting>
123+
&example.outputs.similar;
124+
<screen>
114125
<![CDATA[
115126
filename: . : filetype: dir
116127
filename: .. : filetype: dir
117128
filename: apache : filetype: dir
118129
filename: cgi : filetype: dir
119130
filename: cli : filetype: dir
120131
]]>
121-
</screen>
122-
</example>
123-
</para>
132+
</screen>
133+
</example>
124134
</refsect1>
125135

126136
<refsect1 role="seealso">
127137
&reftitle.seealso;
128-
<para>
129-
<simplelist>
130-
<member><function>is_dir</function></member>
131-
<member><function>readdir</function></member>
132-
<member><function>dir</function></member>
133-
</simplelist>
134-
</para>
138+
<simplelist>
139+
<member><function>readdir</function></member>
140+
<member><function>rewinddir</function></member>
141+
<member><function>closedir</function></member>
142+
<member><function>dir</function></member>
143+
<member><function>is_dir</function></member>
144+
<member><function>glob</function></member>
145+
<member><function>scandir</function></member>
146+
</simplelist>
135147
</refsect1>
136148
</refentry>
137149
<!-- Keep this comment at the end of the file

0 commit comments

Comments
 (0)