select_many and select_many_expr issues #49 and #69

3 files changed, 130 insertions, 3 deletions

diff --git a/README.markdown b/README.markdown
index 2a207a2..a2b2ac7 100644
--- a/README.markdown
+++ b/README.markdown
@@ -33,6 +33,7 @@ Changelog
 * Add support to set multiple properties at once by passing an associative array to `set` method [[sandermarechal](http://github.com/sandermarechal)]
 * Allow an associative array to be passed to `configure` method [[jordanlev](http://github.com/jordanlev)]
 * Patch to allow empty Paris models to be saved ([[j4mie/paris](http://github.com/j4mie/paris)]) issue #58
+* Add `select_many` and `select_many_expr` - closing issues #49 and #69
 
 #### 1.1.1 - release 2011-01-30
 
@@ -240,7 +241,7 @@ Will result in the query:
 
     SELECT * FROM `person`;
 
-The `select` method gives you control over which columns are returned. Call `select` multiple times to specify columns to return.
+The `select` method gives you control over which columns are returned. Call `select` multiple times to specify columns to return or use [`select_many`](#shortcuts-for-specifying-many-columns) to specify many columns at once.
 
     $people = ORM::for_table('person')->select('name')->select('age')->find_many();
 
@@ -264,15 +265,48 @@ Will result in the query:
 
     SELECT `person`.`name` AS `person_name` FROM `person`;
 
-If you wish to override this behaviour (for example, to supply a database expression) you should instead use the `select_expr` method. Again, this takes the alias as an optional second argument.
+If you wish to override this behaviour (for example, to supply a database expression) you should instead use the `select_expr` method. Again, this takes the alias as an optional second argument. You can specify multiple expressions by calling `select_expr` multiple times or use [`select_many_expr`](#shortcuts-for-specifying-many-columns) to specify many expressions at once.
 
     // NOTE: For illustrative purposes only. To perform a count query, use the count() method.
-    $people_count = ORM::for_table('person')->select('COUNT(*)', 'count')->find_many();
+    $people_count = ORM::for_table('person')->select_expr('COUNT(*)', 'count')->find_many();
 
 Will result in the query:
 
     SELECT COUNT(*) AS `count` FROM `person`;
 
+##### Shortcuts for specifying many columns #####
+
+`select_many` and `select_many_expr` are very similar, but they allow you to specify more than one column at once. For example:
+
+    $people = ORM::for_table('person')->select_many('name', 'age')->find_many();
+
+Will result in the query:
+
+    SELECT `name`, `age` FROM `person`;
+
+To specify aliases you need to pass in an array (aliases are set as the key in an associative array):
+
+    $people = ORM::for_table('person')->select_many(array('first_name' => 'name', 'age'), 'height')->find_many();
+
+Will result in the query:
+
+    SELECT `name` AS `first_name`, `age`, `height` FROM `person`;
+
+You can pass the the following styles into `select_many` and `select_many_expr` by mixing and matching arrays and parameters:
+
+    select_many(array('alias' => 'column', 'column2', 'alias2' => 'column3'), 'column4', 'column5')
+    select_many('column', 'column2', 'column3')
+    select_many(array('column', 'column2', 'column3'), 'column4', 'column5')
+
+All the select methods can also be chained with each other so you could do the following to get a neat select query including an expression:
+
+    $people = ORM::for_table('person')->select_many('name', 'age', 'height')->select_expr('NOW()', 'timestamp')->find_many();
+
+Will result in the query:
+
+    SELECT `name`, `age`, `height`, NOW() AS `timestamp` FROM `person`;
+
+
 #### DISTINCT ####
 
 To add a `DISTINCT` keyword before the list of result columns in your query, add a call to `distinct()` to your query chain.
diff --git a/idiorm.php b/idiorm.php
index cd656fe..62332d5 100644
--- a/idiorm.php
+++ b/idiorm.php
@@ -485,6 +485,91 @@
         }
 
         /**
+         * Add columns to the list of columns returned by the SELECT
+         * query. This defaults to '*'. Many columns can be supplied
+         * as either an array or as a list of parameters to the method.
+         * 
+         * Note that the alias must not be numeric - if you want a
+         * numeric alias then prepend it with some alpha chars. eg. a1
+         * 
+         * @example select_many(array('alias' => 'column', 'column2', 'alias2' => 'column3'), 'column4', 'column5');
+         * @example select_many('column', 'column2', 'column3');
+         * @example select_many(array('column', 'column2', 'column3'), 'column4', 'column5');
+         * 
+         * @return \ORM
+         */
+        public function select_many() {
+            $columns = func_get_args();
+            if(!empty($columns)) {
+                $columns = $this->_normalise_select_many_columns($columns);
+                foreach($columns as $alias => $column) {
+                    if(is_numeric($alias)) {
+                        $alias = null;
+                    }
+                    $this->select($column, $alias);
+                }
+            }
+            return $this;
+        }
+
+        /**
+         * Add an unquoted expression to the list of columns returned
+         * by the SELECT query. Many columns can be supplied as either 
+         * an array or as a list of parameters to the method.
+         * 
+         * Note that the alias must not be numeric - if you want a
+         * numeric alias then prepend it with some alpha chars. eg. a1
+         * 
+         * @example select_many_expr(array('alias' => 'column', 'column2', 'alias2' => 'column3'), 'column4', 'column5')
+         * @example select_many_expr('column', 'column2', 'column3')
+         * @example select_many_expr(array('column', 'column2', 'column3'), 'column4', 'column5')
+         * 
+         * @return \ORM
+         */
+        public function select_many_expr() {
+            $columns = func_get_args();
+            if(!empty($columns)) {
+                $columns = $this->_normalise_select_many_columns($columns);
+                foreach($columns as $alias => $column) {
+                    if(is_numeric($alias)) {
+                        $alias = null;
+                    }
+                    $this->select_expr($column, $alias);
+                }
+            }
+            return $this;
+        }
+
+        /**
+         * Take a column specification for the select many methods and convert it
+         * into a normalised array of columns and aliases.
+         * 
+         * It is designed to turn the following styles into a normalised array:
+         * 
+         * array(array('alias' => 'column', 'column2', 'alias2' => 'column3'), 'column4', 'column5'))
+         * 
+         * @param array $columns
+         * @return array
+         */
+        protected function _normalise_select_many_columns($columns) {
+            $return = array();
+            foreach($columns as $column) {
+                if(is_array($column)) {
+                    foreach($column as $key => $value) {
+                        if(!is_numeric($key)) {
+                            $return[$key] = $value;
+                        } else {
+                            $return[] = $value;
+                        }
+                    }
+                } else {
+                    $return[] = $column;
+                }
+            }
+            return $return;
+        }
+
+        /**
          * Add a DISTINCT keyword before the list of columns in the SELECT query
          */
         public function distinct() {
diff --git a/test/test_queries.php b/test/test_queries.php
index e5681db..73b05e1 100644
--- a/test/test_queries.php
+++ b/test/test_queries.php
@@ -160,6 +160,14 @@
     $expected = "SELECT COUNT(*) AS `count` FROM `widget`";
     Tester::check_equal("Literal expression in result columns", $expected);
 
+    ORM::for_table('widget')->select_many(array('widget_name' => 'widget.name'), 'widget_handle')->find_many();
+    $expected = "SELECT `widget`.`name` AS `widget_name`, `widget_handle` FROM `widget`";
+    Tester::check_equal("Aliases in select many result columns", $expected);
+
+    ORM::for_table('widget')->select_many_expr(array('count' => 'COUNT(*)'), 'SUM(widget_order)')->find_many();
+    $expected = "SELECT COUNT(*) AS `count`, SUM(widget_order) FROM `widget`";
+    Tester::check_equal("Literal expression in select many result columns", $expected);
+
     ORM::for_table('widget')->join('widget_handle', array('widget_handle.widget_id', '=', 'widget.id'))->find_many();
     $expected = "SELECT * FROM `widget` JOIN `widget_handle` ON `widget_handle`.`widget_id` = `widget`.`id`";
     Tester::check_equal("Simple join", $expected);