[DOC-CVS] [doc-en] master: Rework documentation for dir functions (#4989)
[email protected] (Gina Peter Banyard via GitHub)
| Newsgroups | php.doc.cvs |
|---|---|
| Message-ID | <[email protected]> |
Author: Gina Peter Banyard (Girgias)
Committer: GitHub (web-flow)
Pusher: Girgias
Date: 2025-11-27T19:40:35Z
Commit: https://github.com/php/doc-en/commit/5c7e9e1351240b5f9e0858cdeba8f754a366d1b7
Raw diff: https://github.com/php/doc-en/commit/5c7e9e1351240b5f9e0858cdeba8f754a366d1b7.diff
Rework documentation for dir functions (#4989)
Include 8.5 deprecation for passing null to use the last opened directory.
Changed paths:
M reference/dir/functions/closedir.xml
M reference/dir/functions/opendir.xml
M reference/dir/functions/readdir.xml
M reference/dir/functions/rewinddir.xml
Diff:
diff --git a/reference/dir/functions/closedir.xml b/reference/dir/functions/closedir.xml
index 74193717a1a9..b4d87b84e5e0 100644
--- a/reference/dir/functions/closedir.xml
+++ b/reference/dir/functions/closedir.xml
@@ -1,6 +1,4 @@
<?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision$ -->
-<!-- splitted from ./en/functions/dir.xml, last change in rev 1.2 -->
<refentry xml:id="function.closedir" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>closedir</refname>
@@ -13,61 +11,84 @@
<type>void</type><methodname>closedir</methodname>
<methodparam choice="opt"><type class="union"><type>resource</type><type>null</type></type><parameter>dir_handle</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
- <para>
+ <simpara>
Closes the directory stream indicated by
- <parameter>dir_handle</parameter>. The stream must have previously
- been opened by <function>opendir</function>.
- </para>
+ <parameter>dir_handle</parameter>.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
- <para>
- <variablelist>
- <varlistentry>
- <term><parameter>dir_handle</parameter></term>
- <listitem>
- <para>
- The directory handle <type>resource</type> previously opened
- with <function>opendir</function>. If the directory handle is
- not specified, the last link opened by <function>opendir</function>
- is assumed.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dir_handle</parameter></term>
+ <listitem>
+ <simpara>
+ A directory handle <type>resource</type> previously opened
+ with <function>opendir</function>.
+ If <parameter>dir_handle</parameter> is &null; the last handle opened
+ using <function>opendir</function> will be used.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
+ <simpara>
&return.void;
- </para>
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="changelog">
+ &reftitle.changelog;
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>&Version;</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>8.5.0</entry>
+ <entry>
+ Using &null; for <parameter>dir_handle</parameter> is now deprecated.
+ Instead, the last opened directory handle should be explicitly provided.
+ </entry>
+ </row>
+ <row>
+ <entry>8.0.0</entry>
+ <entry>
+ <parameter>dir_handle</parameter> is now nullable.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
- <para>
- <example>
- <title><function>closedir</function> example</title>
- <programlisting role="php">
-<![CDATA[
-<?php
-$dir = "/etc/php5/";
+ <simpara>
+ For a complete example refer to the <function>opendir</function>
+ documentation.
+ </simpara>
+ </refsect1>
-// Open a known directory, read directory into variable and then close
-if (is_dir($dir)) {
- if ($dh = opendir($dir)) {
- $directory = readdir($dh);
- closedir($dh);
- }
-}
-?>
-]]>
- </programlisting>
- </example>
- </para>
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><function>opendir</function></member>
+ <member><function>readdir</function></member>
+ <member><function>rewinddir</function></member>
+ <member><function>dir</function></member>
+ <member><function>is_dir</function></member>
+ <member><function>glob</function></member>
+ <member><function>scandir</function></member>
+ </simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
diff --git a/reference/dir/functions/opendir.xml b/reference/dir/functions/opendir.xml
index 7a3afe8386f1..662f0da26168 100644
--- a/reference/dir/functions/opendir.xml
+++ b/reference/dir/functions/opendir.xml
@@ -1,6 +1,4 @@
<?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision$ -->
-<!-- splitted from ./en/functions/dir.xml, last change in rev 1.2 -->
<refentry xml:id="function.opendir" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>opendir</refname>
@@ -14,55 +12,53 @@
<methodparam><type>string</type><parameter>directory</parameter></methodparam>
<methodparam choice="opt"><type class="union"><type>resource</type><type>null</type></type><parameter>context</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
- <para>
+ <simpara>
Opens up a directory handle to be used in subsequent
<function>closedir</function>, <function>readdir</function>, and
<function>rewinddir</function> calls.
- </para>
+ </simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
- <para>
- <variablelist>
- <varlistentry>
- <term><parameter>directory</parameter></term>
- <listitem>
- <para>
- The directory path that is to be opened
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>context</parameter></term>
- <listitem>
- <para>
- For a description of the <parameter>context</parameter> parameter,
- refer to <link linkend="ref.stream">the streams section</link> of
- the manual.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>directory</parameter></term>
+ <listitem>
+ <simpara>
+ The directory path to open.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>context</parameter></term>
+ <listitem>
+ <simpara>
+ For a description of the <parameter>context</parameter> parameter,
+ refer to <link linkend="ref.stream">the streams section</link> of
+ the manual.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
- Returns a directory handle <type>resource</type> on success,
+ <simpara>
+ Returns a directory handle on success,
&return.falseforfailure;
- </para>
+ </simpara>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
&fs.emits.warning.on.failure;
- <para>
+ <simpara>
This may happen if <parameter>directory</parameter> is not a valid directory,
the directory can not be opened due to permission restrictions,
or due to filesystem errors.
- </para>
+ </simpara>
</refsect1>
<refsect1 role="changelog">
@@ -89,49 +85,65 @@
<refsect1 role="examples">
&reftitle.examples;
- <para>
- <example>
- <title><function>opendir</function> example</title>
- <programlisting role="php">
+ <example>
+ <title>
+ List all entries in a directory, skipping the special <literal>.</literal>
+ and <literal>..</literal> directories
+ </title>
+ <simpara>
+ Because file and directory names can be strings that PHP considers "falsy"
+ (e.g. a directory named <literal>"0"</literal>) and
+ <function>readdir</function> returns &false; when it has read all entries
+ in a directory one needs to use the <literal>===</literal>
+ <link linkend="language.operators.comparison">comparison operator</link>
+ to properly distinguish between a directory entry whose name is "falsy"
+ and having read all entries of the directory.
+ </simpara>
+ <programlisting role="php">
<![CDATA[
<?php
-$dir = "/etc/php5/";
-// Open a known directory, and proceed to read its contents
-if (is_dir($dir)) {
- if ($dh = opendir($dir)) {
- while (($file = readdir($dh)) !== false) {
- echo "filename: $file : filetype: " . filetype($dir . $file) . "\n";
+if ($handle = opendir('/path/to/files')) {
+ echo "Entries:\n";
+
+ /* Correctly handling directory entries that may be considered falsy */
+ while (false !== ($entry = readdir($handle))) {
+ if ($entry === '.' || $entry === '..') {
+ continue;
}
- closedir($dh);
+ echo "$entry\n";
}
+
+ closedir($handle);
}
?>
]]>
- </programlisting>
- &example.outputs.similar;
- <screen>
+ </programlisting>
+ &example.outputs.similar;
+ <screen>
<![CDATA[
-filename: . : filetype: dir
-filename: .. : filetype: dir
-filename: apache : filetype: dir
-filename: cgi : filetype: dir
-filename: cli : filetype: dir
+Entries:
+base
+en
+fr
+output.md
+test.php
]]>
- </screen>
- </example>
- </para>
+ </screen>
+ </example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
- <para>
- <simplelist>
- <member><function>is_dir</function></member>
- <member><function>readdir</function></member>
- <member><function>dir</function></member>
- </simplelist>
- </para>
+ <simplelist>
+ <member><function>readdir</function></member>
+ <member><function>rewinddir</function></member>
+ <member><function>closedir</function></member>
+ <member><function>dir</function></member>
+ <member><function>is_dir</function></member>
+ <member><function>glob</function></member>
+ <member><function>scandir</function></member>
+ </simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
diff --git a/reference/dir/functions/readdir.xml b/reference/dir/functions/readdir.xml
index e48b43ff0b67..1f5dc25b7c12 100644
--- a/reference/dir/functions/readdir.xml
+++ b/reference/dir/functions/readdir.xml
@@ -1,6 +1,4 @@
<?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision$ -->
-<!-- splitted from ./en/functions/dir.xml, last change in rev 1.2 -->
<refentry xml:id="function.readdir" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>readdir</refname>
@@ -13,37 +11,35 @@
<type class="union"><type>string</type><type>false</type></type><methodname>readdir</methodname>
<methodparam choice="opt"><type class="union"><type>resource</type><type>null</type></type><parameter>dir_handle</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
- <para>
- Returns the name of the next entry in the directory. The
- entries are returned in the order in which they are stored by
+ <simpara>
+ Returns the name of the next entry in the directory.
+ The entries are returned in the order in which they are stored by
the filesystem.
- </para>
+ </simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
- <para>
- <variablelist>
- <varlistentry>
- <term><parameter>dir_handle</parameter></term>
- <listitem>
- <para>
- The directory handle <type>resource</type> previously opened
- with <function>opendir</function>. If the directory handle is
- not specified, the last link opened by <function>opendir</function>
- is assumed.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dir_handle</parameter></term>
+ <listitem>
+ <simpara>
+ A directory handle <type>resource</type> previously opened
+ with <function>opendir</function>.
+ If <parameter>dir_handle</parameter> is &null; the last handle opened
+ using <function>opendir</function> will be used.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
- Returns the entry name on success&return.falseforfailure;.
- </para>
+ <simpara>
+ Returns the entry name on success,&return.falseforfailure;.
+ </simpara>
&return.falseproblem;
</refsect1>
@@ -58,6 +54,13 @@
</row>
</thead>
<tbody>
+ <row>
+ <entry>8.5.0</entry>
+ <entry>
+ Using &null; for <parameter>dir_handle</parameter> is now deprecated.
+ Instead, the last opened directory handle should be explicitly provided.
+ </entry>
+ </row>
<row>
<entry>8.0.0</entry>
<entry>
@@ -71,77 +74,23 @@
<refsect1 role="examples">
&reftitle.examples;
- <para>
- <example>
- <title>List all entries in a directory</title>
- <para>
- Please note the fashion in which <function>readdir</function>'s
- return value is checked in the examples below. We are explicitly
- testing whether the return value is identical to (equal to and of
- the same type as--see <link linkend="language.operators.comparison">Comparison
- Operators</link> for more information) &false; since otherwise,
- any directory entry whose name evaluates to &false; will stop the
- loop (e.g. a directory named "0").
- </para>
- <programlisting role="php">
-<![CDATA[
-<?php
-
-if ($handle = opendir('/path/to/files')) {
- echo "Directory handle: $handle\n";
- echo "Entries:\n";
-
- /* This is the correct way to loop over the directory. */
- while (false !== ($entry = readdir($handle))) {
- echo "$entry\n";
- }
-
- /* This is the WRONG way to loop over the directory. */
- while ($entry = readdir($handle)) {
- echo "$entry\n";
- }
-
- closedir($handle);
-}
-?>
-]]>
- </programlisting>
- </example>
- </para>
- <para>
- <example>
- <title>
- List all entries in the current directory and strip out <literal>.</literal>
- and <literal>..</literal>
- </title>
- <programlisting role="php">
-<![CDATA[
-<?php
-if ($handle = opendir('.')) {
- while (false !== ($entry = readdir($handle))) {
- if ($entry != "." && $entry != "..") {
- echo "$entry\n";
- }
- }
- closedir($handle);
-}
-?>
-]]>
- </programlisting>
- </example>
- </para>
+ <simpara>
+ For a complete example refer to the <function>opendir</function>
+ documentation.
+ </simpara>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
- <para>
- <simplelist>
- <member><function>is_dir</function></member>
- <member><function>glob</function></member>
- <member><function>opendir</function></member>
- <member><function>scandir</function></member>
- </simplelist>
- </para>
+ <simplelist>
+ <member><function>opendir</function></member>
+ <member><function>rewinddir</function></member>
+ <member><function>closedir</function></member>
+ <member><function>dir</function></member>
+ <member><function>is_dir</function></member>
+ <member><function>glob</function></member>
+ <member><function>scandir</function></member>
+ </simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
diff --git a/reference/dir/functions/rewinddir.xml b/reference/dir/functions/rewinddir.xml
index 77eeb4019131..f71a2a01a438 100644
--- a/reference/dir/functions/rewinddir.xml
+++ b/reference/dir/functions/rewinddir.xml
@@ -1,6 +1,4 @@
<?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision$ -->
-<!-- splitted from ./en/functions/dir.xml, last change in rev 1.2 -->
<refentry xml:id="function.rewinddir" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>rewinddir</refname>
@@ -13,37 +11,34 @@
<type>void</type><methodname>rewinddir</methodname>
<methodparam choice="opt"><type class="union"><type>resource</type><type>null</type></type><parameter>dir_handle</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
- <para>
- Resets the directory stream indicated by
- <parameter>dir_handle</parameter> to the beginning of the
- directory.
- </para>
+ <simpara>
+ Resets the directory stream indicated by <parameter>dir_handle</parameter>
+ to the beginning of the directory.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
- <para>
- <variablelist>
- <varlistentry>
- <term><parameter>dir_handle</parameter></term>
- <listitem>
- <para>
- The directory handle <type>resource</type> previously opened
- with <function>opendir</function>. If the directory handle is
- not specified, the last link opened by <function>opendir</function>
- is assumed.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dir_handle</parameter></term>
+ <listitem>
+ <simpara>
+ A directory handle <type>resource</type> previously opened
+ with <function>opendir</function>.
+ If <parameter>dir_handle</parameter> is &null; the last handle opened
+ using <function>opendir</function> will be used.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
+ <simpara>
&return.void;
- </para>
+ </simpara>
</refsect1>
<refsect1 role="changelog">
@@ -57,6 +52,13 @@
</row>
</thead>
<tbody>
+ <row>
+ <entry>8.5.0</entry>
+ <entry>
+ Using &null; for <parameter>dir_handle</parameter> is now deprecated.
+ Instead, the last opened directory handle should be explicitly provided.
+ </entry>
+ </row>
<row>
<entry>8.0.0</entry>
<entry>
@@ -68,6 +70,26 @@
</informaltable>
</refsect1>
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <simpara>
+ For a complete example refer to the <function>opendir</function>
+ documentation.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><function>opendir</function></member>
+ <member><function>readdir</function></member>
+ <member><function>closedir</function></member>
+ <member><function>dir</function></member>
+ <member><function>is_dir</function></member>
+ <member><function>glob</function></member>
+ <member><function>scandir</function></member>
+ </simplelist>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables: