dbs Tue Aug 30 21:33:48 2005 EDT
Modified files:
/phpdoc/en/reference/pdo/functions PDOStatement-fetchAll.xml
Log:
Document PDO_FETCH_COLUMN, PDO_FETCH_UNIQUE, and PDO_FETCH_GROUP.
http://cvs.php.net/diff.php/phpdoc/en/reference/pdo/functions/PDOStatement-fetchAll.xml?r1=1.6&r2=1.7&ty=u
Index: phpdoc/en/reference/pdo/functions/PDOStatement-fetchAll.xml
diff -u phpdoc/en/reference/pdo/functions/PDOStatement-fetchAll.xml:1.6
phpdoc/en/reference/pdo/functions/PDOStatement-fetchAll.xml:1.7
--- phpdoc/en/reference/pdo/functions/PDOStatement-fetchAll.xml:1.6 Fri May
20 14:51:02 2005
+++ phpdoc/en/reference/pdo/functions/PDOStatement-fetchAll.xml Tue Aug 30
21:33:45 2005
@@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.6 $ -->
+<!-- $Revision: 1.7 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc.
-->
<refentry id="function.PDOStatement-fetchAll">
<refnamediv>
@@ -13,6 +13,7 @@
<methodsynopsis>
<type>array</type><methodname>PDOStatement::fetchAll</methodname>
<methodparam
choice="opt"><type>int</type><parameter>fetch_style</parameter></methodparam>
+ <methodparam
choice="opt"><type>int</type><parameter>column_index</parameter></methodparam>
</methodsynopsis>
&warn.experimental.func;
@@ -30,6 +31,30 @@
<function>PDOStatement::fetch</function>. Defaults to
<literal>PDO_FETCH_BOTH</literal>.
</para>
+ <para>
+ To return an array consisting of all values of a single column from
+ the result set, specify <literal>PDO_FETCH_COLUMN</literal>.
+ </para>
+ <para>
+ To fetch only the unique values of a single column from the result
set,
+ bitwise-OR <literal>PDO_FETCH_COLUMN</literal> with
+ <literal>PDO_FETCH_UNIQUE</literal>.
+ </para>
+ <para>
+ To return an associative array grouped by the values of a specified
+ column, bitwise-OR <literal>PDO_FETCH_COLUMN</literal> with
+ <literal>PDO_FETCH_GROUP</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>column_index</parameter></term>
+ <listitem>
+ <para>
+ Returns the indicated 0-indexed column when the value of
+ <parameter>fetch_style</parameter> is
+ <literal>PDO_FETCH_COLUMN</literal>. Defaults to <literal>0</literal>.
+ </para>
</listitem>
</varlistentry>
</variablelist>
@@ -97,6 +122,92 @@
]]>
</screen>
</example>
+ <example><title>Fetching all values of a single column from a result
set</title>
+ <para>
+ The following example demonstrates how to return all of the values of a
+ single column from a result set, even though the SQL statement itself
+ may return multiple columns per row.
+ </para>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$sth = $dbh->prepare("SELECT name, colour FROM fruit");
+$sth->execute();
+
+/* Fetch all of the values of the first column */
+$result = $sth->fetchAll(PDO_FETCH_COLUMN, 0);
+var_dump($result);
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Array(3)
+(
+ [0] =>
+ string(5) => apple
+ [1] =>
+ string(4) => pear
+ [2] =>
+ string(10) => watermelon
+)
+]]>
+ </screen>
+ </example>
+ <example><title>Grouping all values by a single column</title>
+ <para>
+ The following example demonstrates how to return an associative array
+ grouped by the values of the specified column in the result set. The
+ array contains three keys: values <literal>apple</literal> and
+ <literal>pear</literal> are returned as arrays that contain two
+ different colours, while <literal>watermelon</literal> is
+ returned as an array that contains only one colour.
+ </para>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$insert = $dbh->prepare("INSERT INTO fruit(name, colour) VALUES (?, ?)");
+$insert->execute('apple', 'green');
+$insert->execute('pear', 'yellow');
+
+$sth = $dbh->prepare("SELECT name, colour FROM fruit");
+$sth->execute();
+
+/* Group values by the first column */
+var_dump($sth->fetchAll(PDO_FETCH_COLUMN|PDO_FETCH_GROUP));
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+array(3) {
+ ["apple"]=>
+ array(2) {
+ [0]=>
+ string(5) "green"
+ [1]=>
+ string(3) "red"
+ }
+ ["pear"]=>
+ array(2) {
+ [0]=>
+ string(5) "green"
+ [1]=>
+ string(6) "yellow"
+ }
+ ["watermelon"]=>
+ array(1) {
+ [0]=>
+ string(5) "green"
+ }
+}
+
+]]>
+ </screen>
+ </example>
+
</para>
</refsect1>
