From a0b4a16f5c76de62deae3b66ace067d6d118c6f4 Mon Sep 17 00:00:00 2001
From: Philip Olson <philip@php.net>
Date: Fri, 9 Dec 2011 03:47:42 +0000
Subject: [PATCH] Documented 5.4+ MySQLi_Result iterator support

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@320713 c90b9560-bf6c-de11-be94-00142212c4b1
---
 appendices/migration54.xml                    |  6 +++
 reference/mysqli/mysqli_result.xml            | 31 ++++++++++++++
 .../mysqli/mysqli_result/fetch-assoc.xml      | 40 +++++++++++++++++++
 3 files changed, 77 insertions(+)

diff --git a/appendices/migration54.xml b/appendices/migration54.xml
index 5e74e40f38..9b7944626f 100644
--- a/appendices/migration54.xml
+++ b/appendices/migration54.xml
@@ -424,6 +424,12 @@
    Changes in extension behaviour, and new features:
   </simpara>
   <itemizedlist>
+   <listitem>
+    <simpara>
+     <classname>MySQLi_Result</classname> now implements
+     <classname>Traversable</classname>.
+    </simpara>
+   </listitem>
    <listitem>
     <simpara>
      <!-- Placeholder for "Changes in extension behaviour, and new features". -->
diff --git a/reference/mysqli/mysqli_result.xml b/reference/mysqli/mysqli_result.xml
index 99b6abcd12..5ae52c887f 100644
--- a/reference/mysqli/mysqli_result.xml
+++ b/reference/mysqli/mysqli_result.xml
@@ -12,6 +12,32 @@
    <para>
     Represents the result set obtained from a query against the database.
    </para>
+   
+   <para>
+    <emphasis role="bold">&Changelog;</emphasis>
+   </para>
+
+   <table>
+    <title>&Changelog;</title>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>5.4.0</entry>
+       <entry>
+        <classname>Iterator</classname> support was added, as <classname>MySQLi_Result</classname>
+        now implements <classname>Traversable</classname>.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </table>  
+   
   </section>
 <!-- }}} -->
  
@@ -27,6 +53,11 @@
      <ooclass>
       <classname>MySQLi_Result</classname>
      </ooclass>
+
+     <oointerface>
+      <interfacename>Traversable</interfacename>
+     </oointerface>
+
     </classsynopsisinfo>
 <!-- }}} -->
  
diff --git a/reference/mysqli/mysqli_result/fetch-assoc.xml b/reference/mysqli/mysqli_result/fetch-assoc.xml
index acc07278cd..e7b7eafdf3 100644
--- a/reference/mysqli/mysqli_result/fetch-assoc.xml
+++ b/reference/mysqli/mysqli_result/fetch-assoc.xml
@@ -122,6 +122,46 @@ Arvada (USA)
 Cape Coral (USA)
 Green Bay (USA)
 Santa Clara (USA)
+]]>
+   </screen>
+  </example>
+  <example xml:id="mysqli-result.example.iterator">
+   <title>A <classname>MySQLi_Result</classname> example comparing <classname>iterator</classname> usage</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$c = mysqli_connect('127.0.0.1','user', 'pass');
+
+// Using iterators (support was added with PHP 5.4)
+foreach ( $c->query('SELECT user,host FROM mysql.user') as $row ) {
+    printf("'%s'@'%s'\n", $row['user'], $row['host']);
+}
+
+echo "\n==================\n";
+
+// Not using iterators
+$result = $c->query('SELECT user,host FROM mysql.user');
+while ($row = $result->fetch_assoc()) {
+    printf("'%s'@'%s'\n", $row['user'], $row['host']);
+}
+
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+'root'@'192.168.1.1'
+'root'@'127.0.0.1'
+'dude'@'localhost'
+'lebowski'@'localhost'
+
+==================
+
+'root'@'192.168.1.1'
+'root'@'127.0.0.1'
+'dude'@'localhost'
+'lebowski'@'localhost'
 ]]>
    </screen>
   </example>