From 136c097d3256105d7c93123775d51815b1d433a7 Mon Sep 17 00:00:00 2001 From: Gina Peter Banyard Date: Mon, 10 Nov 2025 04:07:53 +0000 Subject: [PATCH] Rework documentation for dir functions Include 8.5 deprecation for passing null to use the last opened directory. --- reference/dir/functions/closedir.xml | 105 ++++++++++++--------- reference/dir/functions/opendir.xml | 122 +++++++++++++----------- reference/dir/functions/readdir.xml | 131 ++++++++------------------ reference/dir/functions/rewinddir.xml | 70 +++++++++----- 4 files changed, 216 insertions(+), 212 deletions(-) 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 @@ - - closedir @@ -13,61 +11,84 @@ voidclosedir resourcenulldir_handle&null; - + Closes the directory stream indicated by - dir_handle. The stream must have previously - been opened by opendir. - + dir_handle. + &reftitle.parameters; - - - - dir_handle - - - The directory handle resource previously opened - with opendir. If the directory handle is - not specified, the last link opened by opendir - is assumed. - - - - - + + + dir_handle + + + A directory handle resource previously opened + with opendir. + If dir_handle is &null; the last handle opened + using opendir will be used. + + + + &reftitle.returnvalues; - + &return.void; - + + + + + &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 8.5.0 + + Using &null; for dir_handle is now deprecated. + Instead, the last opened directory handle should be explicitly provided. + + + + 8.0.0 + + dir_handle is now nullable. + + + + + &reftitle.examples; - - - <function>closedir</function> example - - + For a complete example refer to the opendir + documentation. + + -// Open a known directory, read directory into variable and then close -if (is_dir($dir)) { - if ($dh = opendir($dir)) { - $directory = readdir($dh); - closedir($dh); - } -} -?> -]]> - - - + + &reftitle.seealso; + + opendir + readdir + rewinddir + dir + is_dir + glob + scandir + - opendir @@ -14,55 +12,53 @@ stringdirectory resourcenullcontext&null; - + Opens up a directory handle to be used in subsequent closedir, readdir, and rewinddir calls. - + &reftitle.parameters; - - - - directory - - - The directory path that is to be opened - - - - - context - - - For a description of the context parameter, - refer to the streams section of - the manual. - - - - - + + + directory + + + The directory path to open. + + + + + context + + + For a description of the context parameter, + refer to the streams section of + the manual. + + + + &reftitle.returnvalues; - - Returns a directory handle resource on success, + + Returns a directory handle on success, &return.falseforfailure; - + &reftitle.errors; &fs.emits.warning.on.failure; - + This may happen if directory is not a valid directory, the directory can not be opened due to permission restrictions, or due to filesystem errors. - + @@ -89,28 +85,43 @@ &reftitle.examples; - - - <function>opendir</function> example - + + + List all entries in a directory, skipping the special <literal>.</literal> + and <literal>..</literal> directories + + + Because file and directory names can be strings that PHP considers "falsy" + (e.g. a directory named "0") and + readdir returns &false; when it has read all entries + in a directory one needs to use the === + comparison operator + to properly distinguish between a directory entry whose name is "falsy" + and having read all entries of the directory. + + ]]> - - &example.outputs.similar; - + + &example.outputs.similar; + - - - + + &reftitle.seealso; - - - is_dir - readdir - dir - - + + readdir + rewinddir + closedir + dir + is_dir + glob + scandir + - readdir @@ -13,37 +11,35 @@ stringfalsereaddir resourcenulldir_handle&null; - - Returns the name of the next entry in the directory. The - entries are returned in the order in which they are stored by + + 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. - + &reftitle.parameters; - - - - dir_handle - - - The directory handle resource previously opened - with opendir. If the directory handle is - not specified, the last link opened by opendir - is assumed. - - - - - + + + dir_handle + + + A directory handle resource previously opened + with opendir. + If dir_handle is &null; the last handle opened + using opendir will be used. + + + + &reftitle.returnvalues; - - Returns the entry name on success&return.falseforfailure;. - + + Returns the entry name on success,&return.falseforfailure;. + &return.falseproblem; @@ -58,6 +54,13 @@ + + 8.5.0 + + Using &null; for dir_handle is now deprecated. + Instead, the last opened directory handle should be explicitly provided. + + 8.0.0 @@ -71,77 +74,23 @@ &reftitle.examples; - - - List all entries in a directory - - Please note the fashion in which readdir'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 Comparison - Operators for more information) &false; since otherwise, - any directory entry whose name evaluates to &false; will stop the - loop (e.g. a directory named "0"). - - - -]]> - - - - - - - List all entries in the current directory and strip out <literal>.</literal> - and <literal>..</literal> - - - -]]> - - - + + For a complete example refer to the opendir + documentation. + &reftitle.seealso; - - - is_dir - glob - opendir - scandir - - + + opendir + rewinddir + closedir + dir + is_dir + glob + scandir + - rewinddir @@ -13,37 +11,34 @@ voidrewinddir resourcenulldir_handle&null; - - Resets the directory stream indicated by - dir_handle to the beginning of the - directory. - + + Resets the directory stream indicated by dir_handle + to the beginning of the directory. + &reftitle.parameters; - - - - dir_handle - - - The directory handle resource previously opened - with opendir. If the directory handle is - not specified, the last link opened by opendir - is assumed. - - - - - + + + dir_handle + + + A directory handle resource previously opened + with opendir. + If dir_handle is &null; the last handle opened + using opendir will be used. + + + + &reftitle.returnvalues; - + &return.void; - + @@ -57,6 +52,13 @@ + + 8.5.0 + + Using &null; for dir_handle is now deprecated. + Instead, the last opened directory handle should be explicitly provided. + + 8.0.0 @@ -68,6 +70,26 @@ + + &reftitle.examples; + + For a complete example refer to the opendir + documentation. + + + + + &reftitle.seealso; + + opendir + readdir + closedir + dir + is_dir + glob + scandir + +