Implemented Doctrine_Pager_Range functionality. This classes enables a...

Implemented Doctrine_Pager_Range functionality. This classes enables a powerful way to generate page ranges (Fowler's pattern) to be used coupled with Doctrine_Pager. Already implemented 2 of the most used ranges: Doctrine_Pager_Range_Jumping and Doctrine_Pager_Range_Sliding.

lib/Doctrine/Pager/Range.php

+<?php
+
+/*
+ *  $Id$
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * This software consists of voluntary contributions made by many individuals
+ * and is licensed under the LGPL. For more information, see
+ * <http://www.phpdoctrine.com>.
+ */
+
+/**
+ * Doctrine_Pager_Range
+ *
+ * @author      Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @package     Doctrine
+ * @subpackage  Pager
+ * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @version     $Revision$
+ * @link        www.phpdoctrine.com
+ * @since       1.0
+ */
+abstract class Doctrine_Pager_Range
+{
+    /**
+     * @var array $options     Custom Doctrine_Pager_Range implementation options
+     */
+	protected $options;
+
+    /**
+     * @var Doctrine_Pager $pager     Doctrine_Pager object related to the pager range
+     */
+    private $pager;
+
+
+    /**
+     * __construct
+     *
+     * @param array $options     Custom subclass implementation options.
+     *                           Default is a blank array
+     * @param Doctrine_Pager $pager     Optional Doctrine_Pager object to be associated
+     * @return void
+     */
+    final public function __construct($options = array(), $pager = null)
+    {
+        $this->setOptions($options);
+
+        if ($pager !== null) {
+            $this->setPager($pager);
+        }
+    }
+
+
+    /**
+     * getPager
+     *
+     * Returns the Doctrine_Pager object related to the pager range
+     *
+     * @return Doctrine_Pager        Doctrine_Pager object related to the pager range
+     */
+    public function getPager()
+    {
+        return $this->pager;
+    }
+
+
+    /**
+     * setPager
+     *
+     * Defines the Doctrine_Pager object related to the pager range and
+     * automatically (re-)initialize Doctrine_Pager_Range
+     *
+     * @param $pager       Doctrine_Pager object related to the pager range
+     * @return void
+     */
+    public function setPager($pager)
+    {
+        $this->pager = $pager;
+
+        // Lazy-load initialization. It only should be called when all
+        // needed information data is ready (this can only happens when we have
+        // options stored and a Doctrine_Pager assocated)
+        $this->initialize();
+    }
+
+
+    /**
+     * getOptions
+     *
+     * Returns the custom Doctrine_Pager_Range implementation options
+     *
+     * @return array        Custom Doctrine_Pager_Range implementation options
+     */
+    public function getOptions()
+    {
+        return $this->options;
+    }
+
+
+    /**
+     * setOptions
+     *
+     * Defines the subclass implementation options
+     *
+     * @param $options       Custom Doctrine_Pager_Range implementation options
+     * @return void
+     */
+    protected function setOptions($options)
+    {
+        $this->options = $options;
+    }
+
+
+    /**
+     * initialize
+     *
+     * Initialize Doctrine_Page_Range subclass which does custom class definitions
+     *
+     * @return void
+     */
+    abstract protected function initialize();
+
+
+    /**
+     * rangeAroundPage
+     *
+     * Calculate and returns an array representing the range around the current page
+     *
+     * @return array
+     */
+    abstract public function rangeAroundPage();
+}

lib/Doctrine/Pager/Range/Jumping.php

+<?php
+
+/*
+ *  $Id$
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * This software consists of voluntary contributions made by many individuals
+ * and is licensed under the LGPL. For more information, see
+ * <http://www.phpdoctrine.com>.
+ */
+ 
+Doctrine::autoload('Doctrine_Pager_Range');
+
+/**
+ * Doctrine_Pager_Range_Jumping
+ *
+ * @author      Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @package     Doctrine
+ * @subpackage  Pager
+ * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @version     $Revision$
+ * @link        www.phpdoctrine.com
+ * @since       1.0
+ */
+class Doctrine_Pager_Range_Jumping extends Doctrine_Pager_Range
+{
+    /**
+     * @var int $chunkLength     Chunk length to be returned
+     */
+    private $chunkLength;
+
+
+    /**
+     * initialize
+     *
+     * Initialize Doctrine_Pager_Range_Jumping and does custom assignments
+     *
+     * @return void
+     */
+    protected function initialize()
+    {
+        if (isset($this->options['chunk'])) {
+            $this->setChunkLength($this->options['chunk']);
+        } else {
+            throw new Doctrine_Pager_Exception('Missing parameter \'chunk\' that must be define in options.');
+        }
+    }
+
+
+    /**
+     * getChunkLength
+     *
+     * Returns the size of the chunk defined
+     *
+     * @return int        Chunk length
+     */
+    public function getChunkLength()
+    {
+        return $this->chunkLength;
+    }
+
+
+    /**
+     * setChunkLength
+     *
+     * Defines the size of the chunk
+     *
+     * @param $chunkLength       Chunk length
+     * @return void
+     */
+    protected function setChunkLength($chunkLength)
+    {
+        $this->chunkLength = $chunkLength;
+    }
+
+
+    /**
+     * rangeAroundPage
+     *
+     * Calculate and returns an array representing the range around the current page
+     *
+     * @return array
+     */
+    public function rangeAroundPage()
+    {
+        $pager = $this->getPager();
+        $page = $pager->getPage();
+
+        // 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);
+    }
+}

lib/Doctrine/Pager/Range/Sliding.php

+<?php
+
+/*
+ *  $Id$
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * This software consists of voluntary contributions made by many individuals
+ * and is licensed under the LGPL. For more information, see
+ * <http://www.phpdoctrine.com>.
+ */
+ 
+Doctrine::autoload('Doctrine_Pager_Range');
+
+/**
+ * Doctrine_Pager_Range_Sliding
+ *
+ * @author      Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @package     Doctrine
+ * @subpackage  Pager
+ * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @version     $Revision$
+ * @link        www.phpdoctrine.com
+ * @since       1.0
+ */
+class Doctrine_Pager_Range_Sliding extends Doctrine_Pager_Range
+{
+    /**
+     * @var int $chunkLength     Chunk length to be returned
+     */
+    private $chunkLength;
+
+
+    /**
+     * initialize
+     *
+     * Initialize Doctrine_Pager_Range_Sliding and does custom assignments
+     *
+     * @return void
+     */
+    protected function initialize()
+    {
+        if (isset($this->options['chunk'])) {
+            $this->setChunkLength($this->options['chunk']);
+        } else {
+            throw new Doctrine_Pager_Exception('Missing parameter \'chunk\' that must be define in options.');
+        }
+    }
+
+
+    /**
+     * getChunkLength
+     *
+     * Returns the size of the chunk defined
+     *
+     * @return int        Chunk length
+     */
+    public function getChunkLength()
+    {
+        return $this->chunkLength;
+    }
+
+
+    /**
+     * setChunkLength
+     *
+     * Defines the size of the chunk
+     *
+     * @param $chunkLength       Chunk length
+     * @return void
+     */
+    protected function setChunkLength($chunkLength)
+    {
+        $this->chunkLength = $chunkLength;
+    }
+
+
+    /**
+     * rangeAroundPage
+     *
+     * Calculate and returns an array representing the range around the current page
+     *
+     * @return array
+     */
+    public function rangeAroundPage()
+    {
+        $pager = $this->getPager();
+        $page = $pager->getPage();
+
+        // Define initial assignments for StartPage and EndPage
+        $startPage = $page - floor($this->getChunkLength() - 1) / 2;
+        $endPage = ($startPage + $this->getChunkLength()) - 1;
+
+        // Check for EndPage out-range
+        if ( $endPage > $pager->getLastPage() ) {
+            $offset = $endPage - $pager->getLastPage();
+
+            $endPage = $pager->getLastPage();
+            $startPage = $startPage - $offset;
+        }
+
+        // Check for StartPage out-range
+        if ( $startPage < $pager->getFirstPage() ) {
+            $startPage = $pager->getFirstPage();
+        }
+
+        return range($startPage, $endPage);
+    }
+}