Doctrine

Timestamp:

01/16/08 20:51:36 (18 months ago)

Author:

guilhermeblanco

Message:

Fixed count bug in Doctrine_Pager that was wrong counting the total of results found. Added 3 new methods: Doctrine_Pager::getExecuted (checks if the Pager was already executed), Doctrine_Pager_Layout::execute (handy access to execute Pager query without having to access Doctrine_Pager instance) and Doctrine_Pager_Layout::processPage (processes the template of a given page and returns the parsed string)

Files:

• branches/0.10/lib/Doctrine/Pager.php (modified) (15 diffs)
• branches/0.10/lib/Doctrine/Pager/Exception.php (modified) (1 diff)
• branches/0.10/lib/Doctrine/Pager/Layout.php (modified) (9 diffs)
• branches/0.10/lib/Doctrine/Pager/Range.php (modified) (1 diff)
• branches/0.10/lib/Doctrine/Pager/Range/Jumping.php (modified) (2 diffs)
• branches/0.10/lib/Doctrine/Pager/Range/Sliding.php (modified) (2 diffs)
• branches/0.9/lib/Doctrine/Pager.php (modified) (15 diffs)
• branches/0.9/lib/Doctrine/Pager/Exception.php (modified) (1 diff)
• branches/0.9/lib/Doctrine/Pager/Layout.php (modified) (9 diffs)
• branches/0.9/lib/Doctrine/Pager/Range.php (modified) (1 diff)
• branches/0.9/lib/Doctrine/Pager/Range/Jumping.php (modified) (2 diffs)
• branches/0.9/lib/Doctrine/Pager/Range/Sliding.php (modified) (2 diffs)
• trunk/lib/Doctrine/Pager.php (modified) (15 diffs)
• trunk/lib/Doctrine/Pager/Exception.php (modified) (1 diff)
• trunk/lib/Doctrine/Pager/Layout.php (modified) (9 diffs)
• trunk/lib/Doctrine/Pager/Range.php (modified) (1 diff)
• trunk/lib/Doctrine/Pager/Range/Jumping.php (modified) (2 diffs)
• trunk/lib/Doctrine/Pager/Range/Sliding.php (modified) (2 diffs)

branches/0.10/lib/Doctrine/Pager.php

@@ -29 +29 @@
  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
  * @version     $Revision$
- * @link        www.phpdoctrine.com
- * @since       1.0
+ * @link        www.phpdoctrine.org
+ * @since       0.9
  */
 class Doctrine_Pager
@@ -59 +59 @@
     protected $_lastPage;
 
+    /**
+     * @var boolean $_executed          Pager was initialized (called "execute" at least once)
+     */
+    protected $_executed;
+
 
 
@@ -65 +70 @@
      *
      * @param mixed $query     Accepts either a Doctrine_Query object or a string 
-         *                        (which does the Doctrine_Query class creation).
+     *                        (which does the Doctrine_Query class creation).
      * @param int $page     Current page
      * @param int $maxPerPage     Maximum itens per page
@@ -72 +77 @@
     public function __construct($query, $page, $maxPerPage = 0)
     {
+        $this->_setExecuted(false);
+
         $this->_setQuery($query);
-
-        $this->_setMaxPerPage($maxPerPage);
         $this->_setPage($page);
 
-        $this->_initialize();
+        $this->setMaxPerPage($maxPerPage);
     }
 
@@ -86 +91 @@
      * Initialize Pager object calculating number of results
      *
-     * @return void
-     */
-    protected function _initialize()
+     * @param $params  Optional parameters to Doctrine_Query::execute
+     * @return void
+     */
+    protected function _initialize($params = array())
     {
         // retrieve the number of items found
-                $count = $this->getQuery()->count();
+        $count = $this->getQuery()->count($params);
         $this->_setNumResults($count);
 
         $this->_adjustOffset();
+
+        $this->_setExecuted(true);
     }
 
@@ -107 +115 @@
     protected function _adjustOffset()
     {
-        // Define new total of pages
-                $this->_setLastPage(
-            max(1, ceil($this->getNumResults() / $this->getMaxPerPage()))
+        if (!$this->getExecuted()) {
+            // Define new total of pages
+            $this->_setLastPage(
+                max(1, ceil($this->getNumResults() / $this->getMaxPerPage()))
+            );
+            $offset = ($this->getPage() - 1) * $this->getMaxPerPage();
+
+            // Assign new offset and limit to Doctrine_Query object
+            $p = $this->getQuery();
+            $p->offset($offset);
+            $p->limit($this->getMaxPerPage());
+        }
+    }
+
+
+    /**
+     * getExecuted
+     *
+     * Returns the check if Pager was already executed at least once
+     *
+     * @return boolen        Pager was executed
+     */
+    public function getExecuted()
+    {
+        return $this->_executed;
+    }
+
+
+    /**
+     * _setExecuted
+     *
+     * Defines if Pager was already executed
+     *
+     * @param $executed       Pager was executed
+     * @return void
+     */
+    protected function _setExecuted($executed)
+    {
+        $this->_executed = $executed;
+    }
+
+
+    /**
+     * getNumResults
+     *
+     * Returns the number of results found
+     *
+     * @return int        the number of results found
+     */
+    public function getNumResults()
+    {
+        if ($this->getExecuted()) {
+            return $this->_numResults;
+        }
+
+        throw new Doctrine_Pager_Exception(
+            'Cannot retrieve the number of results of a not yet executed Pager query'
         );
-        $offset = ($this->getPage() - 1) * $this->getMaxPerPage();
-
-                // Assign new offset and limit to Doctrine_Query object
-        $p = $this->getQuery();
-        $p->offset($offset);
-        $p->limit($this->getMaxPerPage());
-    }
-
-
-    /**
-     * getNumResults
-     *
-     * Returns the number of results found
-     *
-     * @return int        the number of results found
-     */
-    public function getNumResults()
-    {
-        return $this->_numResults;
     }
 
@@ -169 +212 @@
     public function getLastPage()
     {
-        return $this->_lastPage;
+        if ($this->getExecuted()) {
+            return $this->_lastPage;
+        }
+
+        throw new Doctrine_Pager_Exception(
+            'Cannot retrieve the last page number of a not yet executed Pager query'
+        );
     }
 
@@ -213 +262 @@
     public function getNextPage()
     {
-        return min($this->getPage() + 1, $this->getLastPage());
+        if ($this->getExecuted()) {
+            return $this->_lastPage;
+        }
+
+        throw new Doctrine_Pager_Exception(
+            'Cannot retrieve the last page number of a not yet executed Pager query'
+        );return min($this->getPage() + 1, $this->getLastPage());
     }
 
@@ -226 +281 @@
     public function getPreviousPage()
     {
-        return max($this->getPage() - 1, $this->getFirstPage());
+        if ($this->getExecuted()) {
+            return max($this->getPage() - 1, $this->getFirstPage());
+        }
+
+        throw new Doctrine_Pager_Exception(
+            'Cannot retrieve the previous page number of a not yet executed Pager query'
+        );
     }
 
@@ -239 +300 @@
     public function haveToPaginate()
     {
-        return $this->getNumResults() > $this->getMaxPerPage();
+        if ($this->getExecuted()) {
+            return $this->getNumResults() > $this->getMaxPerPage();
+        }
+
+        throw new Doctrine_Pager_Exception(
+            'Cannot know if it is necessary to paginate a not yet executed Pager query'
+        );
     }
 
@@ -254 +321 @@
     {
         $this->_setPage($page);
-        $this->_adjustOffset();
+        $this->_setExecuted(false);
     }
 
@@ -295 +362 @@
      */
     public function setMaxPerPage($max)
-    {
-        $this->_setMaxPerPage($max);
-        $this->_adjustOffset();
-    }
-
-
-    /**
-     * _setMaxPerPage
-     *
-     * Defines the maximum number of itens per page
-     *
-     * @param $max       maximum number of itens per page
-     * @return void
-     */
-    private function _setMaxPerPage($max)
     {
         if ($max > 0) {
@@ -318 +370 @@
             $this->_maxPerPage = abs($max);
         }
+
+        $this->_setExecuted(false);
     }
 
@@ -340 +394 @@
      *
      * @param $query     Accepts either a Doctrine_Query object or a string 
-         *                   (which does the Doctrine_Query class creation).
+     *                   (which does the Doctrine_Query class creation).
      * @return void
      */
@@ -355 +409 @@
     /**
      * execute
-     * executes the query and populates the data set
-     *
-     * @param $params        Optional parameters to Doctrine_Query::execute
-     * @param $hydrationMode        Hyddration Mode of Doctrine_Query::execute 
-         *                              returned ResultSet. Doctrine::Default is FETCH_RECORD
-     * @return Doctrine_Collection            the root collection
+     *
+     * Executes the query, populates the collection and then return it
+     *
+     * @param $params               Optional parameters to Doctrine_Query::execute
+     * @param $hydrationMode        Hydration Mode of Doctrine_Query::execute 
+     *                              returned ResultSet. Doctrine::Default is FETCH_RECORD
+     * @return Doctrine_Collection  The root collection
      */
     public function execute($params = array(), $hydrationMode = Doctrine::FETCH_RECORD)
     {
+        $this->_initialize($params);
+
         return $this->getQuery()->execute($params, $hydrationMode);
     }

branches/0.10/lib/Doctrine/Pager/Exception.php

@@ -31 +31 @@
  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
  * @version     $Revision$
- * @link        www.phpdoctrine.com
- * @since       1.0
+ * @link        www.phpdoctrine.org
+ * @since       0.9
  */
 class Doctrine_Pager_Exception extends Doctrine_Exception

branches/0.10/lib/Doctrine/Pager/Layout.php

@@ -31 +31 @@
  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
  * @version     $Revision$
- * @link        www.phpdoctrine.com
- * @since       1.0
+ * @link        www.phpdoctrine.org
+ * @since       0.9
  */
 class Doctrine_Pager_Layout
@@ -122 +122 @@
 
     /**
+     * execute
+     *
+     * Handy method to execute the query without need to retrieve the Pager instance
+     *
+     * @param $params               Optional parameters to Doctrine_Query::execute
+     * @param $hydrationMode        Hydration Mode of Doctrine_Query::execute 
+     *                              returned ResultSet. Doctrine::Default is FETCH_RECORD
+     * @return Doctrine_Collection  The root collection
+     */
+    public function execute($params = array(), $hydrationMode = Doctrine::FETCH_RECORD)
+    {
+        return $this->getPager()->execute($params, $hydrationMode);
+    }
+
+
+    /**
      * getPagerRange
      *
@@ -256 +272 @@
         $this->_separatorTemplate = $separatorTemplate;
     }
-    
-    
+
+
     /**
      * addMaskReplacement
@@ -280 +296 @@
         }
     }
-    
-    
+
+
     /**
      * removeMaskReplacement
@@ -334 +350 @@
             // Define some optional mask values
             $options['page_number'] = $range[$i];
-            $options['page'] = $range[$i]; // Handy assignment for URLs
-            $options['url'] = $this->_parseUrl($options);
-
-            $str .= $this->_parseTemplate($options);
+
+            $str .= $this->processPage($options);
 
             // Apply separator between pages
@@ -353 +367 @@
     }
 
-    /**
-     * simply calls display, and returns the output.
+
+    /**
+     * processPage
+     *
+     * Parses the template and returns the string of a processed page
+     *
+     * @param array    Optional parameters to be applied in template and url mask
+     * @return string  Processed template for the given page
+     */
+    public function processPage($options = array())
+    {
+        // Check if at least basic options are defined
+        if (!isset($options['page_number'])) {
+            throw new Doctrine_Pager_Exception(
+                'Cannot process template of the given page. ' .
+                'Missing at least one of needed parameters: \'page\' or \'page_number\''
+            );
+
+            // Should never reach here
+            return '';
+        }
+
+        // Assign "page" options index if not defined yet
+        if (!isset($this->_maskReplacements['page']) && !isset($options['page'])) {
+            $options['page'] = $options['page_number'];
+        }
+
+        return $this->_parseTemplate($options);
+    }
+
+
+    /**
+     * Simply calls display, and returns the output.
      */
     public function __toString()
@@ -367 +412 @@
      * Process the template of a given page and return the processed template
      *
-     * @param $options    Optional parameters to be applied in template and url mask
+     * @param array    Optional parameters to be applied in template and url mask
      * @return string  
      */
@@ -374 +419 @@
         $str = '';
 
-        if (isset($options['page_number']) && $options['page_number'] == $this->getPager()->getPage()) {
+        // If given page is the current active one
+        if ($options['page_number'] == $this->getPager()->getPage()) {
             $str = $this->_parseMaskReplacements($this->getSelectedTemplate());
         }
@@ -383 +429 @@
         }
 
+        // Defining "url" options index to allow {%url} mask
+        $options['url'] = $this->_parseUrl($options);
+
         $replacements = array();
-        
+
         foreach ($options as $k => $v) {
             $replacements['{%'.$k.'}'] = $v;

branches/0.10/lib/Doctrine/Pager/Range.php

@@ -29 +29 @@
  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
  * @version     $Revision$
- * @link        www.phpdoctrine.com
- * @since       1.0
+ * @link        www.phpdoctrine.org
+ * @since       0.9
  */
 abstract class Doctrine_Pager_Range

branches/0.10/lib/Doctrine/Pager/Range/Jumping.php

@@ -31 +31 @@
  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
  * @version     $Revision$
- * @link        www.phpdoctrine.com
- * @since       1.0
+ * @link        www.phpdoctrine.org
+ * @since       0.9
  */
 class Doctrine_Pager_Range_Jumping extends Doctrine_Pager_Range
@@ -96 +96 @@
     {
         $pager = $this->getPager();
-        $page = $pager->getPage();
 
-        // Define initial assignments for StartPage and EndPage
-        $startPage = $page - ($page - 1) % $this->getChunkLength();
-        $endPage = ($startPage + $this->getChunkLength()) - 1;
+        if ($pager->getExecuted()) {
+            $page = $pager->getPage();
 
-        // Check for EndPage out-range
-        if ($endPage > $pager->getLastPage()) {
-            $endPage = $pager->getLastPage();
+            // Define initial assignments for StartPage and EndPage
+            $startPage = $page - ($page - 1) % $this->getChunkLength();
+            $endPage = ($startPage + $this->getChunkLength()) - 1;
+
+            // Check for EndPage out-range
+            if ($endPage > $pager->getLastPage()) {
+                $endPage = $pager->getLastPage();
+            }
+
+            // No need to check for out-range in start, it will never happens
+
+            return range($startPage, $endPage);
         }
 
-        // No need to check for out-range in start, it will never happens
-
-        return range($startPage, $endPage);
+        throw new Doctrine_Pager_Exception(
+            'Cannot retrieve the range around the page of a not yet executed Pager query'
+        );
     }
 }

branches/0.10/lib/Doctrine/Pager/Range/Sliding.php

@@ -31 +31 @@
  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
  * @version     $Revision$
- * @link        www.phpdoctrine.com
- * @since       1.0
+ * @link        www.phpdoctrine.org
+ * @since       0.9
  */
 class Doctrine_Pager_Range_Sliding extends Doctrine_Pager_Range
@@ -101 +101 @@
     {
         $pager = $this->getPager();
-        $page  = $pager->getPage();
-        $pages = $pager->getLastPage();
 
-        $chunk = $this->getChunkLength();
-        if ($chunk > $pages) {
-            $chunk = $pages;
+        if ($pager->getExecuted()) {
+            $page  = $pager->getPage();
+            $pages = $pager->getLastPage();
+
+            $chunk = $this->getChunkLength();
+
+            if ($chunk > $pages) {
+                $chunk = $pages;
+            }
+
+            $chunkStart = $page - (floor($chunk / 2));
+            $chunkEnd   = $page + (ceil($chunk / 2)-1);
+
+            if ($chunkStart < 1) {
+                $adjust = 1 - $chunkStart;
+                $chunkStart = 1;
+                $chunkEnd = $chunkEnd + $adjust;
+            }
+
+            if ($chunkEnd > $pages) {
+                $adjust = $chunkEnd - $pages;
+                $chunkStart = $chunkStart - $adjust;
+                $chunkEnd = $pages;
+            }
+
+            return range($chunkStart, $chunkEnd);
         }
 
-        $chunkStart = $page - (floor($chunk / 2));
-        $chunkEnd   = $page + (ceil($chunk / 2)-1);
-
-        if ($chunkStart < 1) {
-            $adjust = 1 - $chunkStart;
-            $chunkStart = 1;
-            $chunkEnd = $chunkEnd + $adjust;
-        }
-        if ($chunkEnd > $pages) {
-            $adjust = $chunkEnd - $pages;
-            $chunkStart = $chunkStart - $adjust;
-            $chunkEnd = $pages;
-        }
-
-        return range($chunkStart, $chunkEnd);
-
+        throw new Doctrine_Pager_Exception(
+            'Cannot retrieve the range around the page of a not yet executed Pager query'
+        );
     }
 }

branches/0.9/lib/Doctrine/Pager.php

@@ -29 +29 @@
  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
  * @version     $Revision$
- * @link        www.phpdoctrine.com
- * @since       1.0
+ * @link        www.phpdoctrine.org
+ * @since       0.9
  */
 class Doctrine_Pager
@@ -59 +59 @@
     protected $_lastPage;
 
+    /**
+     * @var boolean $_executed          Pager was initialized (called "execute" at least once)
+     */
+    protected $_executed;
+
 
 
@@ -65 +70 @@
      *
      * @param mixed $query     Accepts either a Doctrine_Query object or a string 
-         *                        (which does the Doctrine_Query class creation).
+     *                        (which does the Doctrine_Query class creation).
      * @param int $page     Current page
      * @param int $maxPerPage     Maximum itens per page
@@ -72 +77 @@
     public function __construct($query, $page, $maxPerPage = 0)
     {
+        $this->_setExecuted(false);
+
         $this->_setQuery($query);
-
-        $this->_setMaxPerPage($maxPerPage);
         $this->_setPage($page);
 
-        $this->_initialize();
+        $this->setMaxPerPage($maxPerPage);
     }
 
@@ -86 +91 @@
      * Initialize Pager object calculating number of results
      *
-     * @return void
-     */
-    protected function _initialize()
+     * @param $params  Optional parameters to Doctrine_Query::execute
+     * @return void
+     */
+    protected function _initialize($params = array())
     {
         // retrieve the number of items found
-                $count = $this->getQuery()->count();
+        $count = $this->getQuery()->count($params);
         $this->_setNumResults($count);
 
         $this->_adjustOffset();
+
+        $this->_setExecuted(true);
     }
 
@@ -107 +115 @@
     protected function _adjustOffset()
     {
-        // Define new total of pages
-                $this->_setLastPage(
-            max(1, ceil($this->getNumResults() / $this->getMaxPerPage()))
+        if (!$this->getExecuted()) {
+            // Define new total of pages
+            $this->_setLastPage(
+                max(1, ceil($this->getNumResults() / $this->getMaxPerPage()))
+            );
+            $offset = ($this->getPage() - 1) * $this->getMaxPerPage();
+
+            // Assign new offset and limit to Doctrine_Query object
+            $p = $this->getQuery();
+            $p->offset($offset);
+            $p->limit($this->getMaxPerPage());
+        }
+    }
+
+
+    /**
+     * getExecuted
+     *
+     * Returns the check if Pager was already executed at least once
+     *
+     * @return boolen        Pager was executed
+     */
+    public function getExecuted()
+    {
+        return $this->_executed;
+    }
+
+
+    /**
+     * _setExecuted
+     *
+     * Defines if Pager was already executed
+     *
+     * @param $executed       Pager was executed
+     * @return void
+     */
+    protected function _setExecuted($executed)
+    {
+        $this->_executed = $executed;
+    }
+
+
+    /**
+     * getNumResults
+     *
+     * Returns the number of results found
+     *
+     * @return int        the number of results found
+     */
+    public function getNumResults()
+    {
+        if ($this->getExecuted()) {
+            return $this->_numResults;
+        }
+
+        throw new Doctrine_Pager_Exception(
+            'Cannot retrieve the number of results of a not yet executed Pager query'
         );
-        $offset = ($this->getPage() - 1) * $this->getMaxPerPage();
-
-                // Assign new offset and limit to Doctrine_Query object
-        $p = $this->getQuery();
-        $p->offset($offset);
-        $p->limit($this->getMaxPerPage());
-    }
-
-
-    /**
-     * getNumResults
-     *
-     * Returns the number of results found
-     *
-     * @return int        the number of results found
-     */
-    public function getNumResults()
-    {
-        return $this->_numResults;
     }
 
@@ -169 +212 @@
     public function getLastPage()
     {
-        return $this->_lastPage;
+        if ($this->getExecuted()) {
+            return $this->_lastPage;
+        }
+
+        throw new Doctrine_Pager_Exception(
+            'Cannot retrieve the last page number of a not yet executed Pager query'
+        );
     }
 
@@ -213 +262 @@
     public function getNextPage()
     {
-        return min($this->getPage() + 1, $this->getLastPage());
+        if ($this->getExecuted()) {
+            return $this->_lastPage;
+        }
+
+        throw new Doctrine_Pager_Exception(
+            'Cannot retrieve the last page number of a not yet executed Pager query'
+        );return min($this->getPage() + 1, $this->getLastPage());
     }
 
@@ -226 +281 @@
     public function getPreviousPage()
     {
-        return max($this->getPage() - 1, $this->getFirstPage());
+        if ($this->getExecuted()) {
+            return max($this->getPage() - 1, $this->getFirstPage());
+        }
+
+        throw new Doctrine_Pager_Exception(
+            'Cannot retrieve the previous page number of a not yet executed Pager query'
+        );
     }
 
@@ -239 +300 @@
     public function haveToPaginate()
     {
-        return $this->getNumResults() > $this->getMaxPerPage();
+        if ($this->getExecuted()) {
+            return $this->getNumResults() > $this->getMaxPerPage();
+        }
+
+        throw new Doctrine_Pager_Exception(
+            'Cannot know if it is necessary to paginate a not yet executed Pager query'
+        );
     }
 
@@ -254 +321 @@
     {
         $this->_setPage($page);
-        $this->_adjustOffset();
+        $this->_setExecuted(false);
     }
 
@@ -295 +362 @@
      */
     public function setMaxPerPage($max)
-    {
-        $this->_setMaxPerPage($max);
-        $this->_adjustOffset();
-    }
-
-
-    /**
-     * _setMaxPerPage
-     *
-     * Defines the maximum number of itens per page
-     *
-     * @param $max       maximum number of itens per page
-     * @return void
-     */
-    private function _setMaxPerPage($max)
     {
         if ($max > 0) {
@@ -318 +370 @@
             $this->_maxPerPage = abs($max);
         }
+
+        $this->_setExecuted(false);
     }
 
@@ -340 +394 @@
      *
      * @param $query     Accepts either a Doctrine_Query object or a string 
-         *                   (which does the Doctrine_Query class creation).
+     *                   (which does the Doctrine_Query class creation).
      * @return void
      */
@@ -355 +409 @@
     /**
      * execute
-     * executes the query and populates the data set
-     *
-     * @param $params        Optional parameters to Doctrine_Query::execute
-     * @param $hydrationMode        Hyddration Mode of Doctrine_Query::execute 
-         *                              returned ResultSet. Doctrine::Default is FETCH_RECORD
-     * @return Doctrine_Collection            the root collection
+     *
+     * Executes the query, populates the collection and then return it
+     *
+     * @param $params               Optional parameters to Doctrine_Query::execute
+     * @param $hydrationMode        Hydration Mode of Doctrine_Query::execute 
+     *                              returned ResultSet. Doctrine::Default is FETCH_RECORD
+     * @return Doctrine_Collection  The root collection
      */
     public function execute($params = array(), $hydrationMode = Doctrine::FETCH_RECORD)
     {
+        $this->_initialize($params);
+
         return $this->getQuery()->execute($params, $hydrationMode);
     }

branches/0.9/lib/Doctrine/Pager/Exception.php

@@ -31 +31 @@
  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
  * @version     $Revision$
- * @link        www.phpdoctrine.com
- * @since       1.0
+ * @link        www.phpdoctrine.org
+ * @since       0.9
  */
 class Doctrine_Pager_Exception extends Doctrine_Exception

branches/0.9/lib/Doctrine/Pager/Layout.php

@@ -31 +31 @@
  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
  * @version     $Revision$
- * @link        www.phpdoctrine.com
- * @since       1.0
+ * @link        www.phpdoctrine.org
+ * @since       0.9
  */
 class Doctrine_Pager_Layout
@@ -122 +122 @@
 
     /**
+     * execute
+     *
+     * Handy method to execute the query without need to retrieve the Pager instance
+     *
+     * @param $params               Optional parameters to Doctrine_Query::execute
+     * @param $hydrationMode        Hydration Mode of Doctrine_Query::execute 
+     *                              returned ResultSet. Doctrine::Default is FETCH_RECORD
+     * @return Doctrine_Collection  The root collection
+     */
+    public function execute($params = array(), $hydrationMode = Doctrine::FETCH_RECORD)
+    {
+        return $this->getPager()->execute($params, $hydrationMode);
+    }
+
+
+    /**
      * getPagerRange
      *
@@ -256 +272 @@
         $this->_separatorTemplate = $separatorTemplate;
     }
-    
-    
+
+
     /**
      * addMaskReplacement
@@ -280 +296 @@
         }
     }
-    
-    
+
+
     /**
      * removeMaskReplacement
@@ -334 +350 @@
             // Define some optional mask values
             $options['page_number'] = $range[$i];
-            $options['page'] = $range[$i]; // Handy assignment for URLs
-            $options['url'] = $this->_parseUrl($options);
-
-            $str .= $this->_parseTemplate($options);
+
+            $str .= $this->processPage($options);
 
             // Apply separator between pages
@@ -353 +367 @@
     }
 
-    /**
-     * simply calls display, and returns the output.
+
+    /**
+     * processPage
+     *
+     * Parses the template and returns the string of a processed page
+     *
+     * @param array    Optional parameters to be applied in template and url mask
+     * @return string  Processed template for the given page
+     */
+    public function processPage($options = array())
+    {
+        // Check if at least basic options are defined
+        if (!isset($options['page_number'])) {
+            throw new Doctrine_Pager_Exception(
+                'Cannot process template of the given page. ' .
+                'Missing at least one of needed parameters: \'page\' or \'page_number\''
+            );
+
+            // Should never reach here
+            return '';
+        }
+
+        // Assign "page" options index if not defined yet
+        if (!isset($this->_maskReplacements['page']) && !isset($options['page'])) {
+            $options['page'] = $options['page_number'];
+        }
+
+        return $this->_parseTemplate($options);
+    }
+
+
+    /**
+     * Simply calls display, and returns the output.
      */
     public function __toString()
@@ -367 +412 @@
      * Process the template of a given page and return the processed template
      *
-     * @param $options    Optional parameters to be applied in template and url mask
+     * @param array    Optional parameters to be applied in template and url mask
      * @return string  
      */
@@ -374 +419 @@
         $str = '';
 
-        if (isset($options['page_number']) && $options['page_number'] == $this->getPager()->getPage()) {
+        // If given page is the current active one
+        if ($options['page_number'] == $this->getPager()->getPage()) {
             $str = $this->_parseMaskReplacements($this->getSelectedTemplate());
         }
@@ -383 +429 @@
         }
 
+        // Defining "url" options index to allow {%url} mask
+        $options['url'] = $this->_parseUrl($options);
+
         $replacements = array();
-        
+
         foreach ($options as $k => $v) {
             $replacements['{%'.$k.'}'] = $v;

branches/0.9/lib/Doctrine/Pager/Range.php

@@ -29 +29 @@
  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
  * @version     $Revision$
- * @link        www.phpdoctrine.com
- * @since       1.0
+ * @link        www.phpdoctrine.org
+ * @since       0.9
  */
 abstract class Doctrine_Pager_Range

branches/0.9/lib/Doctrine/Pager/Range/Jumping.php

@@ -31 +31 @@
  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
  * @version     $Revision$
- * @link        www.phpdoctrine.com
- * @since       1.0
+ * @link        www.phpdoctrine.org
+ * @since       0.9
  */
 class Doctrine_Pager_Range_Jumping extends Doctrine_Pager_Range
@@ -96 +96 @@
     {
         $pager = $this->getPager();
-        $page = $pager->getPage();
 
-        // Define initial assignments for StartPage and EndPage
-        $startPage = $page - ($page - 1) % $this->getChunkLength();
-        $endPage = ($startPage + $this->getChunkLength()) - 1;
+        if ($pager->getExecuted()) {
+            $page = $pager->getPage();
 
-        // Check for EndPage out-range
-        if ($endPage > $pager->getLastPage()) {
-            $endPage = $pager->getLastPage();
+            // Define initial assignments for StartPage and EndPage
+            $startPage = $page - ($page - 1) % $this->getChunkLength();
+            $endPage = ($startPage + $this->getChunkLength()) - 1;
+
+            // Check for EndPage out-range
+            if ($endPage > $pager->getLastPage()) {
+                $endPage = $pager->getLastPage();
+            }
+
+            // No need to check for out-range in start, it will never happens
+
+            return range($startPage, $endPage);
         }
 
-        // No need to check for out-range in start, it will never happens
-
-        return range($startPage, $endPage);
+        throw new Doctrine_Pager_Exception(
+            'Cannot retrieve the range around the page of a not yet executed Pager query'
+        );
     }
 }

branches/0.9/lib/Doctrine/Pager/Range/Sliding.php

@@ -31 +31 @@
  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
  * @version     $Revision$
- * @link        www.phpdoctrine.com
- * @since       1.0
+ * @link        www.phpdoctrine.org
+ * @since       0.9
  */
 class Doctrine_Pager_Range_Sliding extends Doctrine_Pager_Range
@@ -101 +101 @@
     {
         $pager = $this->getPager();
-        $page  = $pager->getPage();
-        $pages = $pager->getLastPage();
 
-        $chunk = $this->getChunkLength();
-        if ($chunk > $pages) {
-            $chunk = $pages;
+        if ($pager->getExecuted()) {
+            $page  = $pager->getPage();
+            $pages = $pager->getLastPage();
+
+            $chunk = $this->getChunkLength();
+
+            if ($chunk > $pages) {
+                $chunk = $pages;
+            }
+
+            $chunkStart = $page - (floor($chunk / 2));
+            $chunkEnd   = $page + (ceil($chunk / 2)-1);
+
+            if ($chunkStart < 1) {
+                $adjust = 1 - $chunkStart;
+                $chunkStart = 1;
+                $chunkEnd = $chunkEnd + $adjust;
+            }
+
+            if ($chunkEnd > $pages) {
+                $adjust = $chunkEnd - $pages;
+                $chunkStart = $chunkStart - $adjust;
+                $chunkEnd = $pages;
+            }
+
+            return range($chunkStart, $chunkEnd);
         }
 
-        $chunkStart = $page - (floor($chunk / 2));
-        $chunkEnd   = $page + (ceil($chunk / 2)-1);
-
-        if ($chunkStart < 1) {
-            $adjust = 1 - $chunkStart;
-            $chunkStart = 1;
-            $chunkEnd = $chunkEnd + $adjust;
-        }
-        if ($chunkEnd > $pages) {
-            $adjust = $chunkEnd - $pages;
-            $chunkStart = $chunkStart - $adjust;
-            $chunkEnd = $pages;
-        }
-
-        return range($chunkStart, $chunkEnd);
-
+        throw new Doctrine_Pager_Exception(
+            'Cannot retrieve the range around the page of a not yet executed Pager query'
+        );
     }
 }

trunk/lib/Doctrine/Pager.php

@@ -29 +29 @@
  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
  * @version     $Revision$
- * @link        www.phpdoctrine.com
- * @since       1.0
+ * @link        www.phpdoctrine.org
+ * @since       0.9
  */
 class Doctrine_Pager
@@ -59 +59 @@
     protected $_lastPage;
 
+    /**
+     * @var boolean $_executed          Pager was initialized (called "execute" at least once)
+     */
+    protected $_executed;
+
 
 
@@ -65 +70 @@
      *
      * @param mixed $query     Accepts either a Doctrine_Query object or a string 
-         *                        (which does the Doctrine_Query class creation).
+     *                        (which does the Doctrine_Query class creation).
      * @param int $page     Current page
      * @param int $maxPerPage     Maximum itens per page
@@ -72 +77 @@
     public function __construct($query, $page, $maxPerPage = 0)
     {
+        $this->_setExecuted(false);
+
         $this->_setQuery($query);
-
-        $this->_setMaxPerPage($maxPerPage);
         $this->_setPage($page);
 
-        $this->_initialize();
+        $this->setMaxPerPage($maxPerPage);
     }
 
@@ -86 +91 @@
      * Initialize Pager object calculating number of results
      *
-     * @return void
-     */
-    protected function _initialize()
+     * @param $params  Optional parameters to Doctrine_Query::execute
+     * @return void
+     */
+    protected function _initialize($params = array())
     {
         // retrieve the number of items found
-                $count = $this->getQuery()->count();
+        $count = $this->getQuery()->count($params);
         $this->_setNumResults($count);
 
         $this->_adjustOffset();
+
+        $this->_setExecuted(true);
     }
 
@@ -107 +115 @@
     protected function _adjustOffset()
     {
-        // Define new total of pages
-                $this->_setLastPage(
-            max(1, ceil($this->getNumResults() / $this->getMaxPerPage()))
+        if (!$this->getExecuted()) {
+            // Define new total of pages
+            $this->_setLastPage(
+                max(1, ceil($this->getNumResults() / $this->getMaxPerPage()))
+            );
+            $offset = ($this->getPage() - 1) * $this->getMaxPerPage();
+
+            // Assign new offset and limit to Doctrine_Query object
+            $p = $this->getQuery();
+            $p->offset($offset);
+            $p->limit($this->getMaxPerPage());
+        }
+    }
+
+
+    /**
+     * getExecuted
+     *
+     * Returns the check if Pager was already executed at least once
+     *
+     * @return boolen        Pager was executed
+     */
+    public function getExecuted()
+    {
+        return $this->_executed;
+    }
+
+
+    /**
+     * _setExecuted
+     *
+     * Defines if Pager was already executed
+     *
+     * @param $executed       Pager was executed
+     * @return void
+     */
+    protected function _setExecuted($executed)
+    {
+        $this->_executed = $executed;
+    }
+
+
+    /**
+     * getNumResults
+     *
+     * Returns the number of results found
+     *
+     * @return int        the number of results found
+     */
+    public function getNumResults()
+    {
+        if ($this->getExecuted()) {
+            return $this->_numResults;
+        }
+
+        throw new Doctrine_Pager_Exception(
+            'Cannot retrieve the number of results of a not yet executed Pager query'
         );
-        $offset = ($this->getPage() - 1) * $this->getMaxPerPage();
-
-                // Assign new offset and limit to Doctrine_Query object
-        $p = $this->getQuery();
-        $p->offset($offset);
-        $p->limit($this->getMaxPerPage());
-    }
-
-
-    /**
-     * getNumResults
-     *
-     * Returns the number of results found
-     *
-     * @return int        the number of results found
-     */
-    public function getNumResults()
-    {
-        return $this->_numResults;
     }
 
@@ -169 +212 @@
     public function getLastPage()
     {
-        return $this->_lastPage;
+        if ($this->getExecuted()) {
+            return $this->_lastPage;
+        }
+
+        throw new Doctrine_Pager_Exception(
+            'Cannot retrieve the last page number of a not yet executed Pager query'
+        );
     }
 
@@ -213 +262 @@
     public function getNextPage()
     {
-        return min($this->getPage() + 1, $this->getLastPage());
+        if ($this->getExecuted()) {
+            return $this->_lastPage;
+        }
+
+        throw new Doctrine_Pager_Exception(
+            'Cannot retrieve the last page number of a not yet executed Pager query'
+        );return min($this->getPage() + 1, $this->getLastPage());
     }
 
@@ -226 +281 @@
     public function getPreviousPage()
     {
-        return max($this->getPage() - 1, $this->getFirstPage());
+        if ($this->getExecuted()) {
+            return max($this->getPage() - 1, $this->getFirstPage());
+        }
+
+        throw new Doctrine_Pager_Exception(
+            'Cannot retrieve the previous page number of a not yet executed Pager query'
+        );
     }
 
@@ -239 +300 @@
     public function haveToPaginate()
     {
-        return $this->getNumResults() > $this->getMaxPerPage();
+        if ($this->getExecuted()) {
+            return $this->getNumResults() > $this->getMaxPerPage();
+        }
+
+        throw new Doctrine_Pager_Exception(
+            'Cannot know if it is necessary to paginate a not yet executed Pager query'
+        );
     }
 
@@ -254 +321 @@
     {
         $this->_setPage($page);
-        $this->_adjustOffset();
+        $this->_setExecuted(false);
     }
 
@@ -295 +362 @@
      */
     public function setMaxPerPage($max)
-    {
-        $this->_setMaxPerPage($max);
-        $this->_adjustOffset();
-    }
-
-
-    /**
-     * _setMaxPerPage
-     *
-     * Defines the maximum number of itens per page
-     *
-     * @param $max       maximum number of itens per page
-     * @return void
-     */
-    private function _setMaxPerPage($max)
     {
         if ($max > 0) {
@@ -318 +370 @@
             $this->_maxPerPage = abs($max);
         }
+
+        $this->_setExecuted(false);
     }
 
@@ -340 +394 @@
      *
      * @param $query     Accepts either a Doctrine_Query object or a string 
-         *                   (which does the Doctrine_Query class creation).
+     *                   (which does the Doctrine_Query class creation).
      * @return void
      */
@@ -355 +409 @@
     /**
      * execute
-     * executes the query and populates the data set
-     *
-     * @param $params        Optional parameters to Doctrine_Query::execute
-     * @param $hydrationMode        Hyddration Mode of Doctrine_Query::execute 
-         *                              returned ResultSet. Doctrine::Default is FETCH_RECORD
-     * @return Doctrine_Collection            the root collection
+     *
+     * Executes the query, populates the collection and then return it
+     *
+     * @param $params               Optional parameters to Doctrine_Query::execute
+     * @param $hydrationMode        Hydration Mode of Doctrine_Query::execute 
+     *                              returned ResultSet. Doctrine::Default is FETCH_RECORD
+     * @return Doctrine_Collection  The root collection
      */
     public function execute($params = array(), $hydrationMode = Doctrine::FETCH_RECORD)
     {
+        $this->_initialize($params);
+
         return $this->getQuery()->execute($params, $hydrationMode);
     }

trunk/lib/Doctrine/Pager/Exception.php

@@ -31 +31 @@
  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
  * @version     $Revision$
- * @link        www.phpdoctrine.com
- * @since       1.0
+ * @link        www.phpdoctrine.org
+ * @since       0.9
  */
 class Doctrine_Pager_Exception extends Doctrine_Exception

trunk/lib/Doctrine/Pager/Layout.php

@@ -31 +31 @@
  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
  * @version     $Revision$
- * @link        www.phpdoctrine.com
- * @since       1.0
+ * @link        www.phpdoctrine.org
+ * @since       0.9
  */
 class Doctrine_Pager_Layout
@@ -122 +122 @@
 
     /**
+     * execute
+     *
+     * Handy method to execute the query without need to retrieve the Pager instance
+     *
+     * @param $params               Optional parameters to Doctrine_Query::execute
+     * @param $hydrationMode        Hydration Mode of Doctrine_Query::execute 
+     *                              returned ResultSet. Doctrine::Default is FETCH_RECORD
+     * @return Doctrine_Collection  The root collection
+     */
+    public function execute($params = array(), $hydrationMode = Doctrine::FETCH_RECORD)
+    {
+        return $this->getPager()->execute($params, $hydrationMode);
+    }
+
+
+    /**
      * getPagerRange
      *
@@ -256 +272 @@
         $this->_separatorTemplate = $separatorTemplate;
     }
-    
-    
+
+
     /**
      * addMaskReplacement
@@ -280 +296 @@
         }
     }
-    
-    
+
+
     /**
      * removeMaskReplacement
@@ -334 +350 @@
             // Define some optional mask values
             $options['page_number'] = $range[$i];
-            $options['page'] = $range[$i]; // Handy assignment for URLs
-            $options['url'] = $this->_parseUrl($options);
-
-            $str .= $this->_parseTemplate($options);
+
+            $str .= $this->processPage($options);
 
             // Apply separator between pages
@@ -353 +367 @@
     }
 
-    /**
-     * simply calls display, and returns the output.
+
+    /**
+     * processPage
+     *
+     * Parses the template and returns the string of a processed page
+     *
+     * @param array    Optional parameters to be applied in template and url mask
+     * @return string  Processed template for the given page
+     */
+    public function processPage($options = array())
+    {
+        // Check if at least basic options are defined
+        if (!isset($options['page_number'])) {
+            throw new Doctrine_Pager_Exception(
+                'Cannot process template of the given page. ' .
+                'Missing at least one of needed parameters: \'page\' or \'page_number\''
+            );
+
+            // Should never reach here
+            return '';
+        }
+
+        // Assign "page" options index if not defined yet
+        if (!isset($this->_maskReplacements['page']) && !isset($options['page'])) {
+            $options['page'] = $options['page_number'];
+        }
+
+        return $this->_parseTemplate($options);
+    }
+
+
+    /**
+     * Simply calls display, and returns the output.
      */
     public function __toString()
@@ -367 +412 @@
      * Process the template of a given page and return the processed template
      *
-     * @param $options    Optional parameters to be applied in template and url mask
+     * @param array    Optional parameters to be applied in template and url mask
      * @return string  
      */
@@ -374 +419 @@
         $str = '';
 
-        if (isset($options['page_number']) && $options['page_number'] == $this->getPager()->getPage()) {
+        // If given page is the current active one
+        if ($options['page_number'] == $this->getPager()->getPage()) {
             $str = $this->_parseMaskReplacements($this->getSelectedTemplate());
         }
@@ -383 +429 @@
         }
 
+        // Defining "url" options index to allow {%url} mask
+        $options['url'] = $this->_parseUrl($options);
+
         $replacements = array();
-        
+
         foreach ($options as $k => $v) {
             $replacements['{%'.$k.'}'] = $v;

trunk/lib/Doctrine/Pager/Range.php

@@ -29 +29 @@
  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
  * @version     $Revision$
- * @link        www.phpdoctrine.com
- * @since       1.0
+ * @link        www.phpdoctrine.org
+ * @since       0.9
  */
 abstract class Doctrine_Pager_Range

trunk/lib/Doctrine/Pager/Range/Jumping.php

@@ -31 +31 @@
  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
  * @version     $Revision$
- * @link        www.phpdoctrine.com
- * @since       1.0
+ * @link        www.phpdoctrine.org
+ * @since       0.9
  */
 class Doctrine_Pager_Range_Jumping extends Doctrine_Pager_Range
@@ -96 +96 @@
     {
         $pager = $this->getPager();
-        $page = $pager->getPage();
 
-        // Define initial assignments for StartPage and EndPage
-        $startPage = $page - ($page - 1) % $this->getChunkLength();
-        $endPage = ($startPage + $this->getChunkLength()) - 1;
+        if ($pager->getExecuted()) {
+            $page = $pager->getPage();
 
-        // Check for EndPage out-range
-        if ($endPage > $pager->getLastPage()) {
-            $endPage = $pager->getLastPage();
+            // Define initial assignments for StartPage and EndPage
+            $startPage = $page - ($page - 1) % $this->getChunkLength();
+            $endPage = ($startPage + $this->getChunkLength()) - 1;
+
+            // Check for EndPage out-range
+            if ($endPage > $pager->getLastPage()) {
+                $endPage = $pager->getLastPage();
+            }
+
+            // No need to check for out-range in start, it will never happens
+
+            return range($startPage, $endPage);
         }
 
-        // No need to check for out-range in start, it will never happens
-
-        return range($startPage, $endPage);
+        throw new Doctrine_Pager_Exception(
+            'Cannot retrieve the range around the page of a not yet executed Pager query'
+        );
     }
 }

trunk/lib/Doctrine/Pager/Range/Sliding.php

@@ -31 +31 @@
  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
  * @version     $Revision$
- * @link        www.phpdoctrine.com
- * @since       1.0
+ * @link        www.phpdoctrine.org
+ * @since       0.9
  */
 class Doctrine_Pager_Range_Sliding extends Doctrine_Pager_Range
@@ -101 +101 @@
     {
         $pager = $this->getPager();
-        $page  = $pager->getPage();
-        $pages = $pager->getLastPage();
 
-        $chunk = $this->getChunkLength();
-        if ($chunk > $pages) {
-            $chunk = $pages;
+        if ($pager->getExecuted()) {
+            $page  = $pager->getPage();
+            $pages = $pager->getLastPage();
+
+            $chunk = $this->getChunkLength();
+
+            if ($chunk > $pages) {
+                $chunk = $pages;
+            }
+
+            $chunkStart = $page - (floor($chunk / 2));
+            $chunkEnd   = $page + (ceil($chunk / 2)-1);
+
+            if ($chunkStart < 1) {
+                $adjust = 1 - $chunkStart;
+                $chunkStart = 1;
+                $chunkEnd = $chunkEnd + $adjust;
+            }
+
+            if ($chunkEnd > $pages) {
+                $adjust = $chunkEnd - $pages;
+                $chunkStart = $chunkStart - $adjust;
+                $chunkEnd = $pages;
+            }
+
+            return range($chunkStart, $chunkEnd);
         }
 
-        $chunkStart = $page - (floor($chunk / 2));
-        $chunkEnd   = $page + (ceil($chunk / 2)-1);
-
-        if ($chunkStart < 1) {
-            $adjust = 1 - $chunkStart;
-            $chunkStart = 1;
-            $chunkEnd = $chunkEnd + $adjust;
-        }
-        if ($chunkEnd > $pages) {
-            $adjust = $chunkEnd - $pages;
-            $chunkStart = $chunkStart - $adjust;
-            $chunkEnd = $pages;
-        }
-
-        return range($chunkStart, $chunkEnd);
-
+        throw new Doctrine_Pager_Exception(
+            'Cannot retrieve the range around the page of a not yet executed Pager query'
+        );
     }
 }