Update use cases for the mode parameter in PDOStatement::fetchAll() (#…

…3549)

reference/pdo/pdostatement/fetchall.xml

@@ -54,14 +54,22 @@
        <parameter>column</parameter> parameter.
       </para>
       <para>
-       To fetch only the unique values of a single column from the result set,
-       bitwise-OR <constant>PDO::FETCH_COLUMN</constant> with
-       <constant>PDO::FETCH_UNIQUE</constant>.
+       To index the resulting array by a certain column's value (instead of
+       consecutive numbers), put this column's name first in the column
+       list in SQL, and use <constant>PDO::FETCH_UNIQUE</constant>.
+       This column must contain only unique values or some data will be lost.
       </para>
       <para>
-       To return an associative array grouped by the values of a specified
-       column, bitwise-OR <constant>PDO::FETCH_COLUMN</constant> with
-       <constant>PDO::FETCH_GROUP</constant>.
+       To group results in the form of a 3-dimensional array indexed by values
+       of a specified column, put this column's name first in
+       the column list in SQL and use <constant>PDO::FETCH_GROUP</constant>.
+      </para>
+      <para>
+       To group results in the form of a 2-dimensional array
+       use bitwise-OR <constant>PDO::FETCH_GROUP</constant> with
+       <constant>PDO::FETCH_COLUMN</constant>.
+       The results will be grouped by the first column, with the array element's value
+       being a list array of the corresponding entries from the second column.
       </para>
      </listitem>
     </varlistentry>