ZF-4772 - Fixed documentation issues with Zend_Db_Select::union() and added some more test-cases to verify behaviour, "undocumented" behaviour to pass sql strings or select objects which did not work at all before.

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@18196 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/en/module_specs/Zend_Db_Select.xml

@@ -1207,6 +1207,32 @@ $select = $db->select()
 
         </sect3>
 
+        <sect3 id="zend.db.select.building.union">
+            <title>Building a UNION Query</title>
+
+            <para>
+                You can build union queries with <classname>Zend_Db_Select</classname> by passing an array
+                of <classname>Zend_Db_Select</classname> or SQL Query strings into the <methodname>union()</methodname>
+                method. As second parameter you can pass the <constant>Zend_Db_Select::SQL_UNION</constant> or
+                <constant>Zend_Db_Select::SQL_UNION_ALL</constant> constants to specify which type of union you
+                want to perform.
+            </para>
+
+            <example id="zend.db.select.building.union.example">
+                <title>Example of union() method</title>
+
+                <programlisting language="php"><![CDATA[
+$sql1 = $db->select();
+$sql2 = "SELECT ...";
+
+$select = $db->select()
+    ->union(array($sql1, $sql2))
+    ->order("id");
+]]>
+                </programlisting>
+            </example>
+        </sect3>
+
     </sect2>
 
     <sect2 id="zend.db.select.execute">

library/Zend/Db/Select.php

@@ -262,16 +262,27 @@ class Zend_Db_Select
     /**
      * Adds a UNION clause to the query.
      *
-     * The first parameter $select can be a string, an existing Zend_Db_Select
-     * object or an array of either of these types.
+     * The first parameter has to be an array of Zend_Db_Select or
+     * sql query strings.
      *
-     * @param  array|string|Zend_Db_Select $select One or more select clauses for the UNION.
+     * <code>
+     * $sql1 = $db->select();
+     * $sql2 = "SELECT ...";
+     * $select = $db->select()
+     *      ->union(array($sql1, $sql2))
+     *      ->order("id");
+     * </code>
+     *
+     * @param  array $select Array of select clauses for the union.
      * @return Zend_Db_Select This Zend_Db_Select object.
      */
     public function union($select = array(), $type = self::SQL_UNION)
     {
         if (!is_array($select)) {
-            $select = array();
+            require_once 'Zend/Db/Select/Exception.php';
+            throw new Zend_Db_Select_Exception(
+                "union() only accepts an array of Zend_Db_Select instances of sql query strings."
+            );
         }
 
         if (!in_array($type, self::$_unionTypes)) {

tests/Zend/Db/Select/TestCommon.php

@@ -1529,6 +1529,20 @@ abstract class Zend_Db_Select_TestCommon extends Zend_Db_TestSetup
         $this->assertEquals(1, $result[0]['id']);
     }
 
+    public function testSelectUnion_NoArray_ThrowsException()
+    {
+        $this->setExpectedException("Zend_Db_Select_Exception");
+
+        $this->_db->select()->union("string");
+    }
+
+    public function testSelectUnion_InvalidUnionType_ThrowsException()
+    {
+        $this->setExpectedException("Zend_Db_Select_Exception");
+
+        $this->_db->select()->union(array(), "foo");
+    }
+
     public function testSerializeSelect()
     {
         /* checks if the adapter has effectively gotten serialized,