[doc-en] master: Document the CachingIterator and RecursiveCachingIterator methods (#6073)
| From: | Asish Kumar via GitHub | Date: | Fri, 13 Nov 2026 10:16:03 +0000 |
| Subject: | [doc-en] master: Document the CachingIterator and RecursiveCachingIterator methods (#6073) | ||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-23948@lists.php.net to get a copy of this message | ||
Author: Asish Kumar (officialasishkumar)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-11-13T11:15:59+01:00
Commit: https://github.com/php/doc-en/commit/311705fd828e1a14ea539394ec7230f3a78c8f39
Raw diff: https://github.com/php/doc-en/commit/311705fd828e1a14ea539394ec7230f3a78c8f39.diff
Document the CachingIterator and RecursiveCachingIterator methods (#6073)
Fifteen CachingIterator pages and all three RecursiveCachingIterator
pages only had a synopsis and &warn.undocumented.func;, and the
RecursiveCachingIterator class intro was a literal "...". This writes
them out based on ext/spl/spl_iterators.c:
- class intros: explain that a CachingIterator stays one element ahead
of its inner iterator, which is what makes hasNext() possible, and
what FULL_CACHE adds.
- __construct(): what the flags do, that only one string conversion
flag may be given (ValueError as of 8.0.0, InvalidArgumentException
before), and a caution that the default CALL_TOSTRING converts every
element while iterating, so arrays raise a warning and objects
without __toString() throw an Error.
- current(), key(), next(), rewind(), valid(), hasNext(): describe the
look-ahead behaviour; fix the return value of valid() and hasNext(),
which claimed "true on success or false on failure", and the return
type of key(), which was "scalar" instead of mixed.
- getFlags(), setFlags(): the bitmask, which flags cannot be unset
(InvalidArgumentException), and that turning FULL_CACHE on empties
the cache.
- __toString(): what each string conversion flag returns, and the
BadMethodCallException when none is set.
- offsetGet(), offsetSet(), offsetUnset(), offsetExists(), count():
they work on the cache, not the inner iterator, require FULL_CACHE,
and replace the placeholder purposes such as "The offsetGet purpose".
- RecursiveCachingIterator: how children are wrapped with the same
flags, what CATCH_GET_CHILD does, and the TypeError for an iterator
that is not a RecursiveIterator.
Examples are added for hasNext(), getFlags(), setFlags(), __toString(),
offsetGet(), count() and getChildren(). Every example was run on PHP 8.4
and prints the output shown.
Part of #5786
Changed paths:
M reference/spl/cachingiterator.xml
M reference/spl/cachingiterator/construct.xml
M reference/spl/cachingiterator/count.xml
M reference/spl/cachingiterator/current.xml
M reference/spl/cachingiterator/getflags.xml
M reference/spl/cachingiterator/hasnext.xml
M reference/spl/cachingiterator/key.xml
M reference/spl/cachingiterator/next.xml
M reference/spl/cachingiterator/offsetexists.xml
M reference/spl/cachingiterator/offsetget.xml
M reference/spl/cachingiterator/offsetset.xml
M reference/spl/cachingiterator/offsetunset.xml
M reference/spl/cachingiterator/rewind.xml
M reference/spl/cachingiterator/setflags.xml
M reference/spl/cachingiterator/tostring.xml
M reference/spl/cachingiterator/valid.xml
M reference/spl/recursivecachingiterator.xml
M reference/spl/recursivecachingiterator/construct.xml
M reference/spl/recursivecachingiterator/getchildren.xml
M reference/spl/recursivecachingiterator/haschildren.xml
Diff:
diff --git a/reference/spl/cachingiterator.xml b/reference/spl/cachingiterator.xml
index af9b6a3189f1..8e62c41bdbe7 100644
--- a/reference/spl/cachingiterator.xml
+++ b/reference/spl/cachingiterator.xml
@@ -9,9 +9,22 @@
<!-- {{{ CachingIterator intro -->
<section xml:id="cachingiterator.intro">
&reftitle.intro;
- <para>
+ <simpara>
This object supports cached iteration over another iterator.
- </para>
+ </simpara>
+ <simpara>
+ A <classname>CachingIterator</classname> is always one element ahead of
+ its inner iterator: when it moves to an element, it stores the key and
+ value of that element, and then moves the inner iterator forward.
+ This makes it possible to know whether the current element is the last
+ one, with <methodname>CachingIterator::hasNext</methodname>.
+ </simpara>
+ <simpara>
+ With the <constant>CachingIterator::FULL_CACHE</constant> flag, it also
+ keeps every element that has been iterated over, which can then be
+ accessed with array syntax or retrieved with
+ <methodname>CachingIterator::getCache</methodname>.
+ </simpara>
</section>
<!-- }}} -->
diff --git a/reference/spl/cachingiterator/construct.xml
b/reference/spl/cachingiterator/construct.xml
index 3f67e0201f62..edab20cebb82 100644
--- a/reference/spl/cachingiterator/construct.xml
+++ b/reference/spl/cachingiterator/construct.xml
@@ -13,34 +13,112 @@
<methodparam><type>Iterator</type><parameter>iterator</parameter></methodparam>
<methodparam
choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>CachingIterator::CALL_TOSTRING</constant></initializer></methodparam>
</constructorsynopsis>
-
- &warn.undocumented.func;
-
+ <simpara>
+ Creates a <classname>CachingIterator</classname> that iterates over
+ <parameter>iterator</parameter>, staying one element ahead of it.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
- <para>
- <variablelist>
- <varlistentry>
- <term><parameter>iterator</parameter></term>
- <listitem>
- <para>
- Iterator to cache
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>flags</parameter></term>
- <listitem>
- <para>
- Bitmask of flags.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>iterator</parameter></term>
+ <listitem>
+ <simpara>
+ The iterator to cache.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>flags</parameter></term>
+ <listitem>
+ <simpara>
+ A bitmask of the
+ <link linkend="cachingiterator.constants">CachingIterator
constants</link>.
+ </simpara>
+ <simpara>
+ At most one of <constant>CachingIterator::CALL_TOSTRING</constant>,
+ <constant>CachingIterator::TOSTRING_USE_KEY</constant>,
+ <constant>CachingIterator::TOSTRING_USE_CURRENT</constant> and
+ <constant>CachingIterator::TOSTRING_USE_INNER</constant> may be given.
+ It selects what <methodname>CachingIterator::__toString</methodname>
+ returns; if none of them is given, calling it throws an exception.
+ </simpara>
+ <simpara>
+ <constant>CachingIterator::FULL_CACHE</constant> keeps every element
+ that has been iterated over, so that it can be accessed with
+ <link linkend="language.types.array.syntax.accessing">array
syntax</link>
+ or retrieved with <methodname>CachingIterator::getCache</methodname>.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <simpara>
+ Throws a <exceptionname>ValueError</exceptionname> if
+ <parameter>flags</parameter> contains more than one of
+ <constant>CachingIterator::CALL_TOSTRING</constant>,
+ <constant>CachingIterator::TOSTRING_USE_KEY</constant>,
+ <constant>CachingIterator::TOSTRING_USE_CURRENT</constant> and
+ <constant>CachingIterator::TOSTRING_USE_INNER</constant>.
+ </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.0.0</entry>
+ <entry>
+ Now throws a <exceptionname>ValueError</exceptionname> if
+ <parameter>flags</parameter> contains more than one of the string
+ conversion flags; previously, an
+ <exceptionname>InvalidArgumentException</exceptionname> was thrown.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </refsect1>
+
+ <refsect1 role="notes">
+ &reftitle.notes;
+ <caution>
+ <simpara>
+ With <constant>CachingIterator::CALL_TOSTRING</constant>, which is the
+ default, each element is converted to a &string; as soon as the iterator
+ moves to it, whether or not
+ <methodname>CachingIterator::__toString</methodname> is ever called.
+ An element that is an &array; raises an <constant>E_WARNING</constant>,
+ and an object that does not implement
+ <link linkend="object.tostring">__toString()</link> throws an
+ <exceptionname>Error</exceptionname>.
+ To iterate over such elements, pass <parameter>flags</parameter> that do
+ not contain <constant>CachingIterator::CALL_TOSTRING</constant>, such as
+ <literal>0</literal>.
+ </simpara>
+ </caution>
+ </refsect1>
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><methodname>CachingIterator::setFlags</methodname></member>
+ <member><methodname>CachingIterator::__toString</methodname></member>
+
<member><methodname>RecursiveCachingIterator::__construct</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/cachingiterator/count.xml b/reference/spl/cachingiterator/count.xml
index 2219682c72b9..4674e5990a35 100644
--- a/reference/spl/cachingiterator/count.xml
+++ b/reference/spl/cachingiterator/count.xml
@@ -3,7 +3,7 @@
<refentry xml:id="cachingiterator.count" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>CachingIterator::count</refname>
- <refpurpose>The number of elements in the iterator</refpurpose>
+ <refpurpose>Return the number of elements in the cache</refpurpose>
</refnamediv>
<refsect1 role="description">
@@ -12,12 +12,15 @@
<modifier>public</modifier>
<type>int</type><methodname>CachingIterator::count</methodname>
<void/>
</methodsynopsis>
-
- &warn.undocumented.func;
-
- <para>
- May return the number of elements in the iterator.
- </para>
+ <simpara>
+ Returns the number of elements in the cache.
+ This is the number of elements iterated over so far, not the number of
+ elements of the inner iterator. Elements are stored in the cache by key,
+ so an element replaces any earlier element with the same key.
+ </simpara>
+ <simpara>
+ The <constant>CachingIterator::FULL_CACHE</constant> flag must be set.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -27,9 +30,53 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
- The count of the elements iterated over.
- </para>
+ <simpara>
+ Returns the number of elements in the cache.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <simpara>
+ Throws a <exceptionname>BadMethodCallException</exceptionname> if the
+ <constant>CachingIterator::FULL_CACHE</constant> flag is not set.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title><methodname>CachingIterator::count</methodname> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$iterator = new CachingIterator(
+ new ArrayIterator(['a', 'b', 'c']),
+ CachingIterator::FULL_CACHE
+);
+
+foreach ($iterator as $value) {
+ echo $value, ': ', count($iterator), "\n";
+}
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+a: 1
+b: 2
+c: 3
+]]>
+ </screen>
+ </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><methodname>CachingIterator::getCache</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/cachingiterator/current.xml b/reference/spl/cachingiterator/current.xml
index 3727875494b4..089d72129327 100644
--- a/reference/spl/cachingiterator/current.xml
+++ b/reference/spl/cachingiterator/current.xml
@@ -11,14 +11,16 @@
&reftitle.description;
<methodsynopsis role="CachingIterator">
<modifier>public</modifier>
<type>mixed</type><methodname>CachingIterator::current</methodname>
- <void />
+ <void/>
</methodsynopsis>
-
- &warn.undocumented.func;
-
- <para>
- May return the current element in the iteration.
- </para>
+ <simpara>
+ Returns the current element.
+ </simpara>
+ <simpara>
+ As the <classname>CachingIterator</classname> is one element ahead of its
+ inner iterator, this is the element that was stored when the iterator last
+ moved, not the current element of the inner iterator.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -28,18 +30,19 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
- Mixed
- </para>
+ <simpara>
+ Returns the current element, or &null; if the iterator is not
+ <link linkend="cachingiterator.valid">valid</link>.
+ </simpara>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
- <para>
- <simplelist>
- <member><methodname>Iterator::current</methodname></member>
- </simplelist>
- </para>
+ <simplelist>
+ <member><methodname>CachingIterator::key</methodname></member>
+ <member><methodname>CachingIterator::valid</methodname></member>
+ <member><methodname>Iterator::current</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/cachingiterator/getflags.xml b/reference/spl/cachingiterator/getflags.xml
index b114bf91d928..bfa6c685d920 100644
--- a/reference/spl/cachingiterator/getflags.xml
+++ b/reference/spl/cachingiterator/getflags.xml
@@ -12,12 +12,10 @@
<modifier>public</modifier>
<type>int</type><methodname>CachingIterator::getFlags</methodname>
<void/>
</methodsynopsis>
-
- &warn.undocumented.func;
-
- <para>
- Get the bitmask of the flags used for this CachingIterator instance.
- </para>
+ <simpara>
+ Gets the bitmask of the flags used for this
+ <classname>CachingIterator</classname> instance.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -27,9 +25,47 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
- Description...
- </para>
+ <simpara>
+ Returns a bitmask of the
+ <link linkend="cachingiterator.constants">CachingIterator
constants</link>.
+ Use the bitwise <link
linkend="language.operators.bitwise">&</link>
+ operator to check whether a given flag is set.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title>Checking whether a flag is set</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$iterator = new CachingIterator(
+ new ArrayIterator(['a', 'b', 'c']),
+ CachingIterator::TOSTRING_USE_KEY | CachingIterator::FULL_CACHE
+);
+
+var_dump((bool) ($iterator->getFlags() & CachingIterator::FULL_CACHE));
+var_dump((bool) ($iterator->getFlags() & CachingIterator::CALL_TOSTRING));
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+bool(true)
+bool(false)
+]]>
+ </screen>
+ </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><methodname>CachingIterator::setFlags</methodname></member>
+ <member><methodname>CachingIterator::__construct</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/cachingiterator/hasnext.xml b/reference/spl/cachingiterator/hasnext.xml
index b4c71f974a69..37647a31dfb0 100644
--- a/reference/spl/cachingiterator/hasnext.xml
+++ b/reference/spl/cachingiterator/hasnext.xml
@@ -12,9 +12,15 @@
<modifier>public</modifier>
<type>bool</type><methodname>CachingIterator::hasNext</methodname>
<void/>
</methodsynopsis>
-
- &warn.undocumented.func;
-
+ <simpara>
+ Checks whether there is an element after the current one.
+ </simpara>
+ <simpara>
+ As the <classname>CachingIterator</classname> is one element ahead of its
+ inner iterator, this checks whether the inner iterator is valid, which
+ makes it possible to tell whether the current element is the last one
+ before moving past it.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -24,9 +30,46 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
- &return.success;
- </para>
+ <simpara>
+ Returns &true; if there is an element after the current one,
+ &false; otherwise.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title>Detecting the last element</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$fruits = new CachingIterator(new ArrayIterator(['apple', 'banana',
'cherry']));
+
+foreach ($fruits as $fruit) {
+ echo $fruit;
+
+ if ($fruits->hasNext()) {
+ echo ', ';
+ }
+}
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+apple, banana, cherry
+]]>
+ </screen>
+ </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><methodname>CachingIterator::valid</methodname></member>
+ <member><methodname>CachingIterator::next</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/cachingiterator/key.xml b/reference/spl/cachingiterator/key.xml
index a427e0f5c2d4..de0f4b9a127f 100644
--- a/reference/spl/cachingiterator/key.xml
+++ b/reference/spl/cachingiterator/key.xml
@@ -10,15 +10,17 @@
<refsect1 role="description">
&reftitle.description;
<methodsynopsis role="CachingIterator">
- <modifier>public</modifier>
<type>scalar</type><methodname>CachingIterator::key</methodname>
- <void />
+ <modifier>public</modifier>
<type>mixed</type><methodname>CachingIterator::key</methodname>
+ <void/>
</methodsynopsis>
-
- &warn.undocumented.func;
-
- <para>
- This method may return a key for the current element.
- </para>
+ <simpara>
+ Returns the key of the current element.
+ </simpara>
+ <simpara>
+ As the <classname>CachingIterator</classname> is one element ahead of its
+ inner iterator, this is the key that was stored when the iterator last
+ moved, not the current key of the inner iterator.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -26,6 +28,23 @@
&no.function.parameters;
</refsect1>
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <simpara>
+ Returns the key of the current element, or &null; if the iterator is not
+ <link linkend="cachingiterator.valid">valid</link>.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><methodname>CachingIterator::current</methodname></member>
+ <member><methodname>CachingIterator::valid</methodname></member>
+ <member><methodname>Iterator::key</methodname></member>
+ </simplelist>
+ </refsect1>
+
</refentry>
<!-- Keep this comment at the end of the file
diff --git a/reference/spl/cachingiterator/next.xml b/reference/spl/cachingiterator/next.xml
index 3b68e5f6aa39..bab31b950b52 100644
--- a/reference/spl/cachingiterator/next.xml
+++ b/reference/spl/cachingiterator/next.xml
@@ -12,12 +12,17 @@
<modifier>public</modifier>
<type>void</type><methodname>CachingIterator::next</methodname>
<void/>
</methodsynopsis>
-
- &warn.undocumented.func;
-
- <para>
- Move the iterator forward.
- </para>
+ <simpara>
+ Moves the iterator forward.
+ </simpara>
+ <simpara>
+ If the inner iterator is valid, its current key and element become the
+ current key and element of the <classname>CachingIterator</classname>,
+ and are added to the cache if
+ <constant>CachingIterator::FULL_CACHE</constant> is set.
+ The inner iterator is then moved forward.
+ Otherwise, the <classname>CachingIterator</classname> is no longer valid.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -27,9 +32,18 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
+ <simpara>
&return.void;
- </para>
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><methodname>CachingIterator::rewind</methodname></member>
+ <member><methodname>CachingIterator::hasNext</methodname></member>
+ <member><methodname>CachingIterator::valid</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/cachingiterator/offsetexists.xml
b/reference/spl/cachingiterator/offsetexists.xml
index 859b271b0958..92ee3c0738bc 100644
--- a/reference/spl/cachingiterator/offsetexists.xml
+++ b/reference/spl/cachingiterator/offsetexists.xml
@@ -3,7 +3,7 @@
<refentry xml:id="cachingiterator.offsetexists" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>CachingIterator::offsetExists</refname>
- <refpurpose>The offsetExists purpose</refpurpose>
+ <refpurpose>Check whether an element exists in the cache</refpurpose>
</refnamediv>
<refsect1 role="description">
@@ -12,33 +12,54 @@
<modifier>public</modifier>
<type>bool</type><methodname>CachingIterator::offsetExists</methodname>
<methodparam><type>string</type><parameter>key</parameter></methodparam>
</methodsynopsis>
-
- &warn.undocumented.func;
-
+ <simpara>
+ Checks whether an element is stored under <parameter>key</parameter> in
+ the cache.
+ This method is called when <function>isset</function> or
<function>empty</function> is used on the
+ <classname>CachingIterator</classname> with array syntax, such as
+ <code>isset($iterator['key'])</code>.
+ </simpara>
+ <simpara>
+ The <constant>CachingIterator::FULL_CACHE</constant> flag must be set.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
- <para>
- <variablelist>
- <varlistentry>
- <term><parameter>key</parameter></term>
- <listitem>
- <para>
- The index being checked.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
-
+ <variablelist>
+ <varlistentry>
+ <term><parameter>key</parameter></term>
+ <listitem>
+ <simpara>
+ The key being checked.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
- Returns &true; if an entry referenced by the offset exists, &false; otherwise.
- </para>
+ <simpara>
+ Returns &true; if an element is stored under <parameter>key</parameter>
+ in the cache, &false; otherwise.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <simpara>
+ Throws a <exceptionname>BadMethodCallException</exceptionname> if the
+ <constant>CachingIterator::FULL_CACHE</constant> flag is not set.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><methodname>CachingIterator::offsetGet</methodname></member>
+ <member><methodname>CachingIterator::getCache</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/cachingiterator/offsetget.xml
b/reference/spl/cachingiterator/offsetget.xml
index 711a659af549..3d155bf79111 100644
--- a/reference/spl/cachingiterator/offsetget.xml
+++ b/reference/spl/cachingiterator/offsetget.xml
@@ -3,7 +3,7 @@
<refentry xml:id="cachingiterator.offsetget" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>CachingIterator::offsetGet</refname>
- <refpurpose>The offsetGet purpose</refpurpose>
+ <refpurpose>Return an element from the cache</refpurpose>
</refnamediv>
<refsect1 role="description">
@@ -12,33 +12,92 @@
<modifier>public</modifier>
<type>mixed</type><methodname>CachingIterator::offsetGet</methodname>
<methodparam><type>string</type><parameter>key</parameter></methodparam>
</methodsynopsis>
-
- &warn.undocumented.func;
-
+ <simpara>
+ Returns the element stored under <parameter>key</parameter> in the cache.
+ This method is called when the <classname>CachingIterator</classname> is
+ read with <link linkend="language.types.array.syntax.accessing">array
syntax</link>,
+ such as <code>$iterator['key']</code>.
+ </simpara>
+ <simpara>
+ The <constant>CachingIterator::FULL_CACHE</constant> flag must be set.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
- <para>
- <variablelist>
- <varlistentry>
- <term><parameter>key</parameter></term>
- <listitem>
- <para>
- Description...
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
-
+ <variablelist>
+ <varlistentry>
+ <term><parameter>key</parameter></term>
+ <listitem>
+ <simpara>
+ The key of the element to retrieve.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
- Description...
- </para>
+ <simpara>
+ Returns the cached element, or &null; if there is no element with the
+ given <parameter>key</parameter> in the cache.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <simpara>
+ Throws a <exceptionname>BadMethodCallException</exceptionname> if the
+ <constant>CachingIterator::FULL_CACHE</constant> flag is not set.
+ </simpara>
+ <simpara>
+ Emits an <constant>E_WARNING</constant> if there is no element with the
+ given <parameter>key</parameter> in the cache.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title>Accessing elements that have been iterated over</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$iterator = new CachingIterator(
+ new ArrayIterator(['apple' => 3, 'banana' => 5, 'cherry'
=> 7]),
+ CachingIterator::FULL_CACHE
+);
+
+foreach ($iterator as $fruit => $count) {
+ if ($fruit === 'banana') {
+ break;
+ }
+}
+
+var_dump($iterator['apple']);
+var_dump(isset($iterator['cherry']));
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+int(3)
+bool(false)
+]]>
+ </screen>
+ </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><methodname>CachingIterator::offsetExists</methodname></member>
+ <member><methodname>CachingIterator::offsetSet</methodname></member>
+ <member><methodname>CachingIterator::offsetUnset</methodname></member>
+ <member><methodname>CachingIterator::getCache</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/cachingiterator/offsetset.xml
b/reference/spl/cachingiterator/offsetset.xml
index 5708f2f5d870..98d4c946b04c 100644
--- a/reference/spl/cachingiterator/offsetset.xml
+++ b/reference/spl/cachingiterator/offsetset.xml
@@ -3,7 +3,7 @@
<refentry xml:id="cachingiterator.offsetset" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>CachingIterator::offsetSet</refname>
- <refpurpose>The offsetSet purpose</refpurpose>
+ <refpurpose>Set an element in the cache</refpurpose>
</refnamediv>
<refsect1 role="description">
@@ -13,41 +13,63 @@
<methodparam><type>string</type><parameter>key</parameter></methodparam>
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
</methodsynopsis>
-
- &warn.undocumented.func;
-
+ <simpara>
+ Stores <parameter>value</parameter> under <parameter>key</parameter> in
+ the cache.
+ This method is called when a value is assigned to the
+ <classname>CachingIterator</classname> with array syntax, such as
+ <code>$iterator['key'] = $value</code>.
+ The inner iterator is not modified.
+ </simpara>
+ <simpara>
+ The <constant>CachingIterator::FULL_CACHE</constant> flag must be set.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
- <para>
- <variablelist>
- <varlistentry>
- <term><parameter>key</parameter></term>
- <listitem>
- <para>
- The index of the element to be set.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>value</parameter></term>
- <listitem>
- <para>
- The new value for the <parameter>key</parameter>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
-
+ <variablelist>
+ <varlistentry>
+ <term><parameter>key</parameter></term>
+ <listitem>
+ <simpara>
+ The key of the element to be set.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>value</parameter></term>
+ <listitem>
+ <simpara>
+ The new value for the <parameter>key</parameter>.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
+ <simpara>
&return.void;
- </para>
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <simpara>
+ Throws a <exceptionname>BadMethodCallException</exceptionname> if the
+ <constant>CachingIterator::FULL_CACHE</constant> flag is not set.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><methodname>CachingIterator::offsetGet</methodname></member>
+ <member><methodname>CachingIterator::offsetUnset</methodname></member>
+ <member><methodname>CachingIterator::getCache</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/cachingiterator/offsetunset.xml
b/reference/spl/cachingiterator/offsetunset.xml
index 74874aefec18..4df093dec32b 100644
--- a/reference/spl/cachingiterator/offsetunset.xml
+++ b/reference/spl/cachingiterator/offsetunset.xml
@@ -3,7 +3,7 @@
<refentry xml:id="cachingiterator.offsetunset" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>CachingIterator::offsetUnset</refname>
- <refpurpose>The offsetUnset purpose</refpurpose>
+ <refpurpose>Remove an element from the cache</refpurpose>
</refnamediv>
<refsect1 role="description">
@@ -12,33 +12,54 @@
<modifier>public</modifier>
<type>void</type><methodname>CachingIterator::offsetUnset</methodname>
<methodparam><type>string</type><parameter>key</parameter></methodparam>
</methodsynopsis>
-
- &warn.undocumented.func;
-
+ <simpara>
+ Removes the element stored under <parameter>key</parameter> from the cache.
+ This method is called when <function>unset</function> is used on the
+ <classname>CachingIterator</classname> with array syntax, such as
+ <code>unset($iterator['key'])</code>.
+ The inner iterator is not modified.
+ </simpara>
+ <simpara>
+ The <constant>CachingIterator::FULL_CACHE</constant> flag must be set.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
- <para>
- <variablelist>
- <varlistentry>
- <term><parameter>key</parameter></term>
- <listitem>
- <para>
- The index of the element to be unset.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
-
+ <variablelist>
+ <varlistentry>
+ <term><parameter>key</parameter></term>
+ <listitem>
+ <simpara>
+ The key of the element to be removed.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
+ <simpara>
&return.void;
- </para>
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <simpara>
+ Throws a <exceptionname>BadMethodCallException</exceptionname> if the
+ <constant>CachingIterator::FULL_CACHE</constant> flag is not set.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><methodname>CachingIterator::offsetExists</methodname></member>
+ <member><methodname>CachingIterator::offsetSet</methodname></member>
+ <member><methodname>CachingIterator::getCache</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/cachingiterator/rewind.xml b/reference/spl/cachingiterator/rewind.xml
index e38ec7d010e0..e171a031fdca 100644
--- a/reference/spl/cachingiterator/rewind.xml
+++ b/reference/spl/cachingiterator/rewind.xml
@@ -12,12 +12,10 @@
<modifier>public</modifier>
<type>void</type><methodname>CachingIterator::rewind</methodname>
<void/>
</methodsynopsis>
-
- &warn.undocumented.func;
-
- <para>
- Rewind the iterator.
- </para>
+ <simpara>
+ Rewinds the inner iterator, empties the cache, and then moves to the first
+ element as <methodname>CachingIterator::next</methodname> does.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -27,9 +25,17 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
+ <simpara>
&return.void;
- </para>
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><methodname>CachingIterator::next</methodname></member>
+ <member><methodname>CachingIterator::getCache</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/cachingiterator/setflags.xml b/reference/spl/cachingiterator/setflags.xml
index d975b5e6d72b..d0929c2802dc 100644
--- a/reference/spl/cachingiterator/setflags.xml
+++ b/reference/spl/cachingiterator/setflags.xml
@@ -3,7 +3,7 @@
<refentry xml:id="cachingiterator.setflags" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>CachingIterator::setFlags</refname>
- <refpurpose>The setFlags purpose</refpurpose>
+ <refpurpose>Set the flags for the CachingIterator object</refpurpose>
</refnamediv>
<refsect1 role="description">
@@ -12,36 +12,126 @@
<modifier>public</modifier>
<type>void</type><methodname>CachingIterator::setFlags</methodname>
<methodparam><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
-
- &warn.undocumented.func;
-
- <para>
- Set the flags for the CachingIterator object.
- </para>
+ <simpara>
+ Replaces the flags of the <classname>CachingIterator</classname> with
+ <parameter>flags</parameter>.
+ </simpara>
+ <simpara>
+ Turning <constant>CachingIterator::FULL_CACHE</constant> on empties the
+ cache; elements are added to it from the next move of the iterator onwards.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
- <para>
- <variablelist>
- <varlistentry>
- <term><parameter>flags</parameter></term>
- <listitem>
- <para>
- Bitmask of the flags to set.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
-
+ <variablelist>
+ <varlistentry>
+ <term><parameter>flags</parameter></term>
+ <listitem>
+ <simpara>
+ A bitmask of the
+ <link linkend="cachingiterator.constants">CachingIterator
constants</link>.
+ At most one of <constant>CachingIterator::CALL_TOSTRING</constant>,
+ <constant>CachingIterator::TOSTRING_USE_KEY</constant>,
+ <constant>CachingIterator::TOSTRING_USE_CURRENT</constant> and
+ <constant>CachingIterator::TOSTRING_USE_INNER</constant> may be given.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
+ <simpara>
&return.void;
- </para>
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <simpara>
+ Throws a <exceptionname>ValueError</exceptionname> if
+ <parameter>flags</parameter> contains more than one of
+ <constant>CachingIterator::CALL_TOSTRING</constant>,
+ <constant>CachingIterator::TOSTRING_USE_KEY</constant>,
+ <constant>CachingIterator::TOSTRING_USE_CURRENT</constant> and
+ <constant>CachingIterator::TOSTRING_USE_INNER</constant>.
+ </simpara>
+ <simpara>
+ Throws an <exceptionname>InvalidArgumentException</exceptionname> if
+ <constant>CachingIterator::CALL_TOSTRING</constant> or
+ <constant>CachingIterator::TOSTRING_USE_INNER</constant> is currently set
+ and <parameter>flags</parameter> does not contain it, as these flags
+ cannot be unset.
+ </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.0.0</entry>
+ <entry>
+ Now throws a <exceptionname>ValueError</exceptionname> if
+ <parameter>flags</parameter> contains more than one of the string
+ conversion flags; previously, an
+ <exceptionname>InvalidArgumentException</exceptionname> was thrown.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title>Turning on the full cache</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$iterator = new CachingIterator(new ArrayIterator(['a', 'b', 'c']),
0);
+$iterator->setFlags(CachingIterator::FULL_CACHE);
+
+foreach ($iterator as $value) {
+ // ...
+}
+
+var_dump($iterator->getCache());
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+array(3) {
+ [0]=>
+ string(1) "a"
+ [1]=>
+ string(1) "b"
+ [2]=>
+ string(1) "c"
+}
+]]>
+ </screen>
+ </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><methodname>CachingIterator::getFlags</methodname></member>
+ <member><methodname>CachingIterator::__construct</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/cachingiterator/tostring.xml b/reference/spl/cachingiterator/tostring.xml
index 8e906df6e598..b1e1703aa8c9 100644
--- a/reference/spl/cachingiterator/tostring.xml
+++ b/reference/spl/cachingiterator/tostring.xml
@@ -12,12 +12,49 @@
<modifier>public</modifier>
<type>string</type><methodname>CachingIterator::__toString</methodname>
<void/>
</methodsynopsis>
-
- &warn.undocumented.func;
-
- <para>
- Get the string representation of the current element.
- </para>
+ <simpara>
+ Gets the string representation of the current element.
+ What is returned depends on the flags of the
+ <classname>CachingIterator</classname>:
+ </simpara>
+ <variablelist>
+ <varlistentry>
+ <term><constant>CachingIterator::CALL_TOSTRING</constant></term>
+ <listitem>
+ <simpara>
+ The current element converted to a &string;.
+ The conversion is done when the iterator moves to the element.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>CachingIterator::TOSTRING_USE_KEY</constant></term>
+ <listitem>
+ <simpara>
+ The key of the current element converted to a &string;.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>CachingIterator::TOSTRING_USE_CURRENT</constant></term>
+ <listitem>
+ <simpara>
+ The current element converted to a &string;.
+ The conversion is done when this method is called.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>CachingIterator::TOSTRING_USE_INNER</constant></term>
+ <listitem>
+ <simpara>
+ The inner iterator converted to a &string;.
+ The conversion is done when the iterator moves to the element, before
+ the inner iterator is moved forward.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</refsect1>
<refsect1 role="parameters">
@@ -27,9 +64,56 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
+ <simpara>
The <type>string</type> representation of the current element.
- </para>
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <simpara>
+ Throws a <exceptionname>BadMethodCallException</exceptionname> if none of
+ <constant>CachingIterator::CALL_TOSTRING</constant>,
+ <constant>CachingIterator::TOSTRING_USE_KEY</constant>,
+ <constant>CachingIterator::TOSTRING_USE_CURRENT</constant> and
+ <constant>CachingIterator::TOSTRING_USE_INNER</constant> is set.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title>Using the keys as the string representation</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$iterator = new CachingIterator(
+ new ArrayIterator(['apple' => 3, 'banana' => 5]),
+ CachingIterator::TOSTRING_USE_KEY
+);
+
+foreach ($iterator as $count) {
+ echo $iterator, ': ', $count, "\n";
+}
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+apple: 3
+banana: 5
+]]>
+ </screen>
+ </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><methodname>CachingIterator::__construct</methodname></member>
+ <member><methodname>CachingIterator::setFlags</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/cachingiterator/valid.xml b/reference/spl/cachingiterator/valid.xml
index ae90d208da04..118b95cd20e4 100644
--- a/reference/spl/cachingiterator/valid.xml
+++ b/reference/spl/cachingiterator/valid.xml
@@ -12,12 +12,14 @@
<modifier>public</modifier>
<type>bool</type><methodname>CachingIterator::valid</methodname>
<void/>
</methodsynopsis>
-
- &warn.undocumented.func;
-
- <para>
- Check whether the current element is valid.
- </para>
+ <simpara>
+ Checks whether the current element is valid.
+ </simpara>
+ <simpara>
+ A <classname>CachingIterator</classname> has no current element until
+ <methodname>CachingIterator::rewind</methodname> is called, which
+ &foreach; does automatically.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -27,9 +29,17 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
- &return.success;
- </para>
+ <simpara>
+ Returns &true; if the current element is valid, &false; otherwise.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><methodname>CachingIterator::hasNext</methodname></member>
+ <member><methodname>CachingIterator::rewind</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/recursivecachingiterator.xml b/reference/spl/recursivecachingiterator.xml
index 47d0b80c542d..0f7ee9bca004 100644
--- a/reference/spl/recursivecachingiterator.xml
+++ b/reference/spl/recursivecachingiterator.xml
@@ -9,9 +9,13 @@
<!-- {{{ RecursiveCachingIterator intro -->
<section xml:id="recursivecachingiterator.intro">
&reftitle.intro;
- <para>
- ...
- </para>
+ <simpara>
+ This object supports cached iteration over a
+ <interfacename>RecursiveIterator</interfacename>.
+ The children of each element are also iterated over by a
+ <classname>RecursiveCachingIterator</classname>, created with the same
+ flags.
+ </simpara>
</section>
<!-- }}} -->
diff --git a/reference/spl/recursivecachingiterator/construct.xml
b/reference/spl/recursivecachingiterator/construct.xml
index f1cc3c85b855..18ef9b1a906f 100644
--- a/reference/spl/recursivecachingiterator/construct.xml
+++ b/reference/spl/recursivecachingiterator/construct.xml
@@ -13,48 +13,98 @@
<methodparam><type>Iterator</type><parameter>iterator</parameter></methodparam>
<methodparam
choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>RecursiveCachingIterator::CALL_TOSTRING</constant></initializer></methodparam>
</constructorsynopsis>
- <para>
+ <simpara>
Constructs a new <classname>RecursiveCachingIterator</classname>,
which consists of a passed in <parameter>iterator</parameter>.
- </para>
-
- &warn.undocumented.func;
-
+ </simpara>
+ <simpara>
+ Whether the current element has children is checked when the iterator
+ moves to it. If it does, its children are wrapped in a new
+ <classname>RecursiveCachingIterator</classname> created with the same
+ <parameter>flags</parameter>, which
+ <methodname>RecursiveCachingIterator::getChildren</methodname> returns.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
- <para>
- <variablelist>
- <varlistentry>
- <term><parameter>iterator</parameter></term>
- <listitem>
- <para>
- The iterator being used.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>flags</parameter></term>
- <listitem>
- <para>
- The flags. Use <constant>CALL_TOSTRING</constant> to call
- <methodname>RecursiveCachingIterator::__toString</methodname> for every element
(the default),
- and/or <constant>CATCH_GET_CHILD</constant> to catch exceptions when trying to
get children.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>iterator</parameter></term>
+ <listitem>
+ <simpara>
+ The iterator being used. It must be a
+ <interfacename>RecursiveIterator</interfacename>.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>flags</parameter></term>
+ <listitem>
+ <simpara>
+ A bitmask of the
+ <link linkend="cachingiterator.constants">CachingIterator
constants</link>,
+ as for <methodname>CachingIterator::__construct</methodname>.
+ </simpara>
+ <simpara>
+ With <constant>CachingIterator::CATCH_GET_CHILD</constant>, an exception
+ thrown by the <methodname>RecursiveIterator::hasChildren</methodname> or
+ <methodname>RecursiveIterator::getChildren</methodname> method of the
+ inner iterator is discarded, and the current element is treated as
+ having no children.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <simpara>
+ Throws a <exceptionname>TypeError</exceptionname> if
+ <parameter>iterator</parameter> is not a
+ <interfacename>RecursiveIterator</interfacename>.
+ </simpara>
+ <simpara>
+ Throws a <exceptionname>ValueError</exceptionname> if
+ <parameter>flags</parameter> contains more than one of
+ <constant>CachingIterator::CALL_TOSTRING</constant>,
+ <constant>CachingIterator::TOSTRING_USE_KEY</constant>,
+ <constant>CachingIterator::TOSTRING_USE_CURRENT</constant> and
+ <constant>CachingIterator::TOSTRING_USE_INNER</constant>.
+ </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.0.0</entry>
+ <entry>
+ Now throws a <exceptionname>ValueError</exceptionname> if
+ <parameter>flags</parameter> contains more than one of the string
+ conversion flags; previously, an
+ <exceptionname>InvalidArgumentException</exceptionname> was thrown.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
- <para>
- <simplelist>
- <member><methodname>CachingIterator::__construct</methodname></member>
- </simplelist>
- </para>
+ <simplelist>
+ <member><methodname>CachingIterator::__construct</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/recursivecachingiterator/getchildren.xml
b/reference/spl/recursivecachingiterator/getchildren.xml
index 2ae0feaa6326..dc0058031e70 100644
--- a/reference/spl/recursivecachingiterator/getchildren.xml
+++ b/reference/spl/recursivecachingiterator/getchildren.xml
@@ -11,9 +11,12 @@
<modifier>public</modifier> <type
class="union"><type>RecursiveCachingIterator</type><type>null</type></type><methodname>RecursiveCachingIterator::getChildren</methodname>
<void/>
</methodsynopsis>
-
- &warn.undocumented.func;
-
+ <simpara>
+ Returns the children of the current element, wrapped in a
+ <classname>RecursiveCachingIterator</classname> that has the same flags.
+ The children are retrieved from the inner iterator when the iterator moves
+ to the element, so the same object is returned until the iterator moves on.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -23,9 +26,59 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
- The inner iterator's children, as a RecursiveCachingIterator; or &null; if there is no
children.
- </para>
+ <simpara>
+ The children of the current element, as a
+ <classname>RecursiveCachingIterator</classname>;
+ or &null; if the current element has no children.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title>Iterating over children</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$iterator = new RecursiveCachingIterator(
+ new RecursiveArrayIterator(['a' => 1, 'b' => ['c' => 2,
'd' => 3], 'e' => 4]),
+ 0
+);
+
+foreach ($iterator as $key => $value) {
+ if (!$iterator->hasChildren()) {
+ echo $key, ' = ', $value, "\n";
+ continue;
+ }
+
+ echo $key, ":\n";
+ $children = $iterator->getChildren();
+ foreach ($children as $childKey => $childValue) {
+ echo ' ', $childKey, ' = ', $childValue, $children->hasNext() ?
'' : ' (last)', "\n";
+ }
+}
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+a = 1
+b:
+ c = 2
+ d = 3 (last)
+e = 4
+]]>
+ </screen>
+ </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+
<member><methodname>RecursiveCachingIterator::hasChildren</methodname></member>
+ <member><methodname>RecursiveIterator::getChildren</methodname></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/spl/recursivecachingiterator/haschildren.xml
b/reference/spl/recursivecachingiterator/haschildren.xml
index 4dbd0d85340a..bb0a18837cae 100644
--- a/reference/spl/recursivecachingiterator/haschildren.xml
+++ b/reference/spl/recursivecachingiterator/haschildren.xml
@@ -11,12 +11,13 @@
<modifier>public</modifier>
<type>bool</type><methodname>RecursiveCachingIterator::hasChildren</methodname>
<void/>
</methodsynopsis>
-
- &warn.undocumented.func;
-
+ <simpara>
+ Checks whether the current element has children.
+ The inner iterator is asked when the iterator moves to the element, so
+ this method returns the result that was stored at that time.
+ </simpara>
</refsect1>
-
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
@@ -24,9 +25,17 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
- &true; if the inner iterator has children, otherwise &false;
- </para>
+ <simpara>
+ Returns &true; if the current element has children, &false; otherwise.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+
<member><methodname>RecursiveCachingIterator::getChildren</methodname></member>
+ <member><methodname>RecursiveIterator::hasChildren</methodname></member>
+ </simplelist>
</refsect1>
</refentry>