Change the children and descendants APIs to be more consistent and to

remove Gallery3 concepts from ORM_MPTT.

The following API methods:
  ORM_MPTT::children
  ORM_MPTT::children_count
  ORM_MPTT::descendants
  ORM_MPTT::descendants_count

All now take a $where clause that allow you to pass through additional
field parameters.

old API:
  $album->children(10, 0, "photos")
  $album->children_count("photos")

new API:
  $album->children(10, 0, array("type" => "photos"))
  $album->children_count(array("type" => "photos"))

This gives us a more flexible API and simplifies the code.  While I
was in there, I changed the way we deal with default orderby values so
that we just assign the default value in the function definition,
which allows us to get rid of all conditionals in the implementation
which results in simpler code.

4 files changed, 51 insertions, 56 deletions

diff --git a/modules/gallery/helpers/gallery_rss.php b/modules/gallery/helpers/gallery_rss.php
index 7daf6170..8e887368 100644
--- a/modules/gallery/helpers/gallery_rss.php
+++ b/modules/gallery/helpers/gallery_rss.php
@@ -50,8 +50,9 @@ class gallery_rss_Core {
 
       $feed->children = $item
         ->viewable()
-        ->descendants($limit, $offset, "photo");
-      $feed->max_pages = ceil($item->viewable()->descendants_count("photo") / $limit);
+        ->descendants($limit, $offset, array("type" => "photo"));
+      $feed->max_pages = ceil(
+        $item->viewable()->descendants_count(array("type" => "photo")) / $limit);
       $feed->title = p::purify($item->title);
       $feed->link = url::abs_site("albums/{$item->id}");
       $feed->description = nl2br(p::purify($item->description));
diff --git a/modules/gallery/libraries/ORM_MPTT.php b/modules/gallery/libraries/ORM_MPTT.php
index cde049cd..9d716d8b 100644
--- a/modules/gallery/libraries/ORM_MPTT.php
+++ b/modules/gallery/libraries/ORM_MPTT.php
@@ -146,35 +146,30 @@ class ORM_MPTT_Core extends ORM {
    * @chainable
    * @param   integer  SQL limit
    * @param   integer  SQL offset
-   * @param   string   type to return
+   * @param   array    additional where clauses
    * @param   array    orderby
    * @return array ORM
    */
-  function children($limit=null, $offset=0, $type=null, $orderby=null) {
-    $this->where("parent_id", $this->id);
-    if ($type) {
-      $this->where("type", $type);
-    }
-    if (empty($orderby)) {
-      $this->orderby("id", "ASC");
-    } else {
-      $this->orderby($orderby);
-    }
-    return $this->find_all($limit, $offset);
+  function children($limit=null, $offset=0, $where=array(), $orderby=array("id", "ASC")) {
+    return $this
+      ->where("parent_id", $this->id)
+      ->where($where)
+      ->orderby($orderby)
+      ->find_all($limit, $offset);
   }
 
   /**
    * Return all of the children of this node, ordered by id.
    *
    * @chainable
-   * @param   string  type to return
+   * @param   array    additional where clauses
    * @return array ORM
    */
-  function children_count($type=null) {
-    if ($type) {
-      $this->where("type", $type);
-    }
-    return $this->where("parent_id", $this->id)->count_all();
+  function children_count($where=array()) {
+    return $this
+      ->where($where)
+      ->where("parent_id", $this->id)
+      ->count_all();
   }
 
   /**
@@ -182,39 +177,31 @@ class ORM_MPTT_Core extends ORM {
    *
    * @param   integer  SQL limit
    * @param   integer  SQL offset
-   * @param   string   type to return
+   * @param   array    additional where clauses
    * @param   array    orderby
    * @return object ORM_Iterator
    */
-  function descendants($limit=null, $offset=0, $type=null, $orderby=null) {
-    $this->where("left_ptr >", $this->left_ptr)
-      ->where("right_ptr <=", $this->right_ptr);
-    if ($type) {
-      $this->where("type", $type);
-    }
-
-    if (empty($orderby)) {
-      $this->orderby("id", "ASC");
-    } else {
-      $this->orderby($orderby);
-    }
-
-    return $this->find_all($limit, $offset);
+  function descendants($limit=null, $offset=0, $where=array(), $orderby=array("id", "ASC")) {
+    return $this
+      ->where("left_ptr >", $this->left_ptr)
+      ->where("right_ptr <=", $this->right_ptr)
+      ->where($where)
+      ->orderby($orderby)
+      ->find_all($limit, $offset);
   }
 
   /**
    * Return the count of all the children of the specified type.
    *
-   * @param   string   type to count
+   * @param    array    additional where clauses
    * @return   integer  child count
    */
-  function descendants_count($type=null) {
-    $this->where("left_ptr >", $this->left_ptr)
-      ->where("right_ptr <=", $this->right_ptr);
-    if ($type) {
-      $this->where("type", $type);
-    }
-    return $this->count_all();
+  function descendants_count($where=array()) {
+    return $this
+      ->where("left_ptr >", $this->left_ptr)
+      ->where("right_ptr <=", $this->right_ptr)
+      ->where($where)
+      ->count_all();
   }
 
   /**
diff --git a/modules/gallery/models/item.php b/modules/gallery/models/item.php
index 3498e0db..c4b9826f 100644
--- a/modules/gallery/models/item.php
+++ b/modules/gallery/models/item.php
@@ -521,31 +521,38 @@ class Item_Model extends ORM_MPTT {
   }
 
   /**
-   * Return all of the children of this node, ordered by the defined sort order.
+   * Return all of the children of this album.  Unless you specify a specific sort order, the
+   * results will be ordered by this album's sort order.
    *
    * @chainable
    * @param   integer  SQL limit
    * @param   integer  SQL offset
-   * @param   string   type to return
+   * @param   array    additional where clauses
    * @param   array    orderby
    * @return array ORM
    */
-  function children($limit=null, $offset=0, $type=null,  $orderby=null) {
+  function children($limit=null, $offset=0, $where=array(), $orderby=null) {
     if (empty($orderby)) {
       $orderby = array($this->sort_column => $this->sort_order);
     }
-    return parent::children($limit, $offset, $type, $orderby);
+    return parent::children($limit, $offset, $where, $orderby);
   }
 
   /**
-   * Return all of the children of the specified type, ordered by the defined sort order.
+   * Return the children of this album, and all of it's sub-albums.  Unless you specify a specific
+   * sort order, the results will be ordered by this album's sort order.  Note that this
+   * album's sort order is imposed on all sub-albums, regardless of their sort order.
+   *
+   * @chainable
    * @param   integer  SQL limit
    * @param   integer  SQL offset
-   * @param   string   type to return
+   * @param   array    additional where clauses
    * @return object ORM_Iterator
    */
-  function descendants($limit=null, $offset=0, $type=null) {
-    return parent::descendants($limit, $offset, $type,
-                               array($this->sort_column => $this->sort_order));
+  function descendants($limit=null, $offset=0, $where=array(), $orderby=null) {
+    if (empty($orderby)) {
+      $orderby = array($this->sort_column => $this->sort_order);
+    }
+    return parent::descendants($limit, $offset, $where, $orderby);
   }
 }
diff --git a/modules/gallery/tests/ORM_MPTT_Test.php b/modules/gallery/tests/ORM_MPTT_Test.php
index 943810c3..f77f1f34 100644
--- a/modules/gallery/tests/ORM_MPTT_Test.php
+++ b/modules/gallery/tests/ORM_MPTT_Test.php
@@ -177,8 +177,8 @@ class ORM_MPTT_Test extends Unit_Test_Case {
     $parent->reload();
 
     $this->assert_equal(3, $parent->descendants()->count());
-    $this->assert_equal(2, $parent->descendants(null, 0, "photo")->count());
-    $this->assert_equal(1, $parent->descendants(null, 0, "album")->count());
+    $this->assert_equal(2, $parent->descendants(null, 0, array("type" => "photo"))->count());
+    $this->assert_equal(1, $parent->descendants(null, 0, array("type" => "album"))->count());
   }
 
   public function descendant_limit_test() {
@@ -215,7 +215,7 @@ class ORM_MPTT_Test extends Unit_Test_Case {
     $parent->reload();
 
     $this->assert_equal(3, $parent->descendants_count());
-    $this->assert_equal(2, $parent->descendants_count("photo"));
-    $this->assert_equal(1, $parent->descendants_count("album"));
+    $this->assert_equal(2, $parent->descendants_count(array("type" => "photo")));
+    $this->assert_equal(1, $parent->descendants_count(array("type" => "album")));
   }
 }