mirror of
https://github.com/php/doc-en.git
synced 2026-03-24 07:42:10 +01:00
Rework documentation for dir functions (#4989)
Include 8.5 deprecation for passing null to use the last opened directory.
This commit is contained in:
Gina Peter Banyard
committed by
GitHub
GitHub
parent
480cc8a9ef
commit
5c7e9e1351
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user