adding a pagination api

ref #24

Pagination/ChillPaginationTwig.php

@@ -0,0 +1,76 @@
+<?php
+
+/*
+ * Chill is a software for social workers
+ *
+ * Copyright (C) 2016, Champs Libres Cooperative SCRLFS, 
+ * <http://www.champs-libres.coop>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+namespace Chill\MainBundle\Pagination;
+
+/**
+ * add twig function to render pagination
+ *
+ * @author Julien Fastré <julien.fastre@champs-libres.coop>
+ * @author Champs Libres <info@champs-libres.coop>
+ */
+class ChillPaginationTwig extends \Twig_Extension
+{
+    const LONG_TEMPLATE = 'ChillMainBundle:Pagination:long.html.twig';
+    const SHORT_TEMPLATE = 'ChillMainBundle:Pagination:short.html.twig';
+    
+    public function getName()
+    {
+        return 'chill_pagination';
+    }
+    
+    public function getFunctions()
+    {
+        return array(
+           new \Twig_SimpleFunction(
+                 'chill_pagination',  
+                 array($this, 'paginationRender'),
+                 array(
+                    'needs_environment' => true,
+                    'is_safe' => ['html']
+                 )
+            )
+        );
+    }
+    
+    public function paginationRender(
+          \Twig_Environment $env, 
+          PaginatorInterface $paginator, 
+          $template = 'ChillMainBundle:Pagination:long.html.twig'
+    ) {
+        switch ($template) {
+            case 'long':
+                $t = self::LONG_TEMPLATE;
+                break;
+            case 'short':
+                $t = self::SHORT_TEMPLATE;
+                break;
+            default:
+                $t = $template;
+        }
+        
+        return $env->render($t, array(
+           'paginator' => $paginator,
+           'current' => $paginator->getCurrentPage()->getNumber()
+        ));
+    }
+}

Pagination/Page.php

@@ -0,0 +1,102 @@
+<?php
+
+/*
+ * Chill is a software for social workers
+ * Copyright (C) 2016 Champs-Libres Coopérative <info@champs-libres.coop>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+namespace Chill\MainBundle\Pagination;
+
+use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
+
+/**
+ * a page is an element of a pagination
+ *
+ * @author Julien Fastré <julien.fastre@champs-libres.coop>
+ * @author Champs Libres <info@champs-libres.coop>
+ */
+class Page implements PageInterface
+{
+    /**
+     *
+     * @var UrlGeneratorInterface
+     */
+    protected $urlGenerator;
+    
+    /**
+     * the number of the current page
+     *
+     * @var int
+     */
+    protected $number;
+    
+    /**
+     * The route for the current page
+     *
+     * @var string
+     */
+    protected $route;
+    
+    /**
+     * Parameters for the route to the current page
+     *
+     * @var array
+     */
+    protected $routeParameters;
+    
+    /**
+     * the number of item per page
+     *
+     * @var int
+     */
+    protected $itemPerPage;
+
+
+    public function __construct(
+          $number, 
+          $itemPerPage,
+          UrlGeneratorInterface $urlGenerator,
+          $route,
+          array $routeParameters
+    ) {
+        $this->urlGenerator = $urlGenerator;
+        $this->number = $number;
+        $this->itemPerPage = $itemPerPage;
+        $this->route = $route;
+        $this->routeParameters = $routeParameters;
+    }
+    
+    public function generateUrl()
+    {
+        return $this->urlGenerator->generate($this->route, $this->routeParameters);
+    }
+
+    public function getFirstItemNumber()
+    {
+        return ($this->number - 1) * $this->itemPerPage;
+    }
+
+    public function getLastItemNumber()
+    {
+        return $this->number * $this->itemPerPage - 1;
+    }
+
+    public function getNumber()
+    {
+        return $this->number;
+    }
+
+}

Pagination/PageGenerator.php

@@ -0,0 +1,73 @@
+<?php
+
+/*
+ * Chill is a software for social workers
+ * Copyright (C) 2016 Champs-Libres Coopérative <info@champs-libres.coop>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+namespace Chill\MainBundle\Pagination;
+
+/**
+ * PageGenerator associated with a Paginator
+ *
+ * @author Julien Fastré <julien.fastre@champs-libres.coop>
+ * @author Champs Libres <info@champs-libres.coop>
+ */
+class PageGenerator implements \Iterator
+{
+    /**
+     *
+     * @var Paginator
+     */
+    protected $paginator;
+    
+    /**
+     *
+     * @var int
+     */
+    protected $current = 1;
+    
+    public function __construct(Paginator $paginator) 
+    {
+        $this->paginator = $paginator;;
+    }
+    
+    public function current()
+    {
+        return $this->paginator->getPage($current);
+    }
+
+    public function key()
+    {
+        return $this->current;
+    }
+
+    public function next()
+    {
+        $this->current++;
+    }
+
+    public function rewind()
+    {
+        $this->current = 1;
+    }
+
+    public function valid()
+    {
+        return $this->current > 0 
+              && $this->current <= $this->paginator->countPages();
+    }
+}

Pagination/PageInterface.php

@@ -0,0 +1,43 @@
+<?php
+
+/*
+ * Chill is a software for social workers
+ * Copyright (C) 2016 Champs-Libres Coopérative <info@champs-libres.coop>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+namespace Chill\MainBundle\Pagination;
+
+/**
+ * Represents a page included in a pagination
+ *
+ * @author Julien Fastré <julien.fastre@champs-libres.coop>
+ */
+interface PageInterface
+{
+    public function generateUrl();
+    
+    /**
+     * get the page number.
+     * 
+     * The first page number is 1. 
+     */
+    public function getNumber();
+    
+    public function getFirstItemNumber();
+    
+    public function getLastItemNumber();
+    
+}

Pagination/Paginator.php

@@ -0,0 +1,246 @@
+<?php
+
+/*
+ * Chill is a software for social workers
+ * Copyright (C) 2016 Champs-Libres Coopérative <info@champs-libres.coop>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+namespace Chill\MainBundle\Pagination;
+
+use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
+
+
+/**
+ * Standard paginator class.
+ * 
+ * Represent a set of paginated pages;
+ *
+ * @author Julien Fastré <julien.fastre@champs-libres.coop>
+ * @author Champs Libres <info@champs-libres.coop>
+ */
+class Paginator implements PaginatorInterface
+{
+    /**
+     * The number of total items
+     *
+     * @var int
+     */
+    protected $totalItems;
+    
+    /**
+     * the number of items on a single page
+     *
+     * @var int
+     */
+    protected $itemPerPage;
+    /**
+     * The number of the current page
+     *
+     * @var int
+     */
+    protected $currentPageNumber;
+    
+    /**
+     * the route of the pages
+     *
+     * @var string
+     */
+    protected $route;
+    
+    /**
+     * the parameters of the route
+     *
+     * @var string[]
+     */
+    protected $routeParameters;
+    
+    /**
+     * the generator for url
+     *
+     * @var UrlGeneratorInterface
+     */
+    protected $urlGenerator;
+    
+    /**
+     * the key in the GET parameter to indicate the page number in 
+     * generated routes
+     *
+     * @var string
+     */
+    protected $pageKey;
+    
+    /**
+     * the key in the GET parameter to indicate the number of item per page
+     *
+     * @var string 
+     */
+    protected $itemPerPageKey;
+
+
+    public function __construct(
+          $totalItems,
+          $itemPerPage,
+          $currentPageNumber,
+          $route,
+          array $routeParameters,
+          UrlGeneratorInterface $urlGenerator,
+          $pageKey,
+          $itemPerPageKey
+    ) {
+        $this->totalItems = $totalItems;
+        $this->itemPerPage = $itemPerPage;
+        $this->currentPageNumber = $currentPageNumber;
+        $this->route = $route;
+        $this->routeParameters = $routeParameters;
+        $this->urlGenerator = $urlGenerator;
+        $this->pageKey = $pageKey;
+        $this->itemPerPageKey = $itemPerPageKey;
+    }
+
+    public function count()
+    {
+        return $this->countPages();
+    }
+
+    /**
+     * 
+     * @return \Chill\MainBundle\Pagination\Page
+     */
+    public function getCurrentPage()
+    {
+        return $this->getPage($this->currentPageNumber);
+    }
+
+    public function getCurrentPageFirstItemNumber()
+    {
+        return $this->getCurrentPage()->getFirstItemNumber();
+    }
+    
+    public function isCurrentPage(PageInterface $page)
+    {
+        return $page->getNumber() === $this->currentPageNumber;
+    }
+
+        public function getItemPerPage()
+    {
+        return $this->itemPerPage;
+    }
+    
+    public function setItemPerPage($itemPerPage)
+    {
+        $this->itemPerPage = $itemPerPage;
+    }
+
+        public function getTotalItems()
+    {
+        return $this->totalItems;
+    }
+
+    public function countPages()
+    {
+        $nb = floor($this->totalItems / $this->itemPerPage);
+        
+        if ($this->totalItems % $this->itemPerPage > 0) {
+            $nb++;
+        }
+        
+        return $nb == 0 ? 1 : (int) $nb;
+    }
+
+    /**
+     * 
+     * @return \Chill\MainBundle\Pagination\Page
+     * @throws \RuntimeException if the next page does not exists
+     */
+    public function getNextPage()
+    {
+        if (!$this->hasNextPage()) {
+            throw new \RuntimeException("this page has no next page");
+        }
+        
+        return $this->getPage($this->currentPageNumber + 1);
+    }
+
+    /**
+     * 
+     * @return \Chill\MainBundle\Pagination\Page
+     * @throws \RuntimeException if the next page does not exists
+     */
+    public function getPreviousPage()
+    {
+        if (!$this->hasPreviousPage()) {
+            throw new \RuntimeException("this page has no previous page");
+        }
+        
+        return $this->getPage($this->currentPageNumber - 1);
+    }
+
+    /**
+     * 
+     * @return bool
+     */
+    public function hasNextPage()
+    {
+        return $this->hasPage($this->currentPageNumber + 1);
+    }
+
+    /**
+     * 
+     * @return bool
+     */
+    public function hasPreviousPage()
+    {
+        return $this->hasPage($this->currentPageNumber - 1);
+    }
+    
+    public function hasPage($number)
+    {
+        return $number > 0 and 
+              $number <= $this->countPages();
+    }
+
+    
+    /**
+     * 
+     * @param type $number
+     * @return \Chill\MainBundle\Pagination\Page
+     */
+    public function getPage($number) {
+        if (!$this->hasPage($number)) {
+            throw new \RuntimeException("The page with number $number does not "
+                  . "exists");
+        }
+        
+        return new Page(
+              $number, 
+              $this->itemPerPage,
+              $this->urlGenerator,
+              $this->route,
+              array_merge($this->routeParameters, array(
+                 $this->pageKey => $number,
+                 $this->itemPerPageKey => $this->itemPerPage
+              ))
+              );
+    }
+
+    public function getPagesGenerator()
+    {
+        for ($i = 1; $i <= $this->countPages(); $i++) {
+            yield $this->getPage($i);
+        }
+    }
+
+}

Pagination/PaginatorFactory.php

@@ -0,0 +1,140 @@
+<?php
+
+/*
+ * Chill is a software for social workers
+ * Copyright (C) 2016 Champs-Libres Coopérative <info@champs-libres.coop>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+namespace Chill\MainBundle\Pagination;
+
+use Symfony\Component\Routing\RouterInterface;
+use Symfony\Component\HttpFoundation\RequestStack;
+
+/**
+ * Create paginator instances
+ *
+ * @author Julien Fastré <julien.fastre@champs-libres.coop>
+ * @author Champs Libres <info@champs-libres.coop>
+ */
+class PaginatorFactory
+{
+    /**
+     * the default item per page. This may be overriden by
+     * the request or inside the paginator.
+     *
+     * @var int
+     */
+    private $itemPerPage;
+    
+    /**
+     * the router and generator for url 
+     *
+     * @var RouterInterface
+     */
+    private $router;
+    
+    /**
+     * the request stack
+     *
+     * @var RequestStack
+     */
+    private $requestStack;
+    
+    const DEFAULT_CURRENT_PAGE_KEY = 'page';
+    const DEFAULT_ITEM_PER_NUMBER_KEY = 'item_per_page';
+    const DEFAULT_PAGE_NUMBER = 1;
+    
+    
+    public function __construct(
+          RequestStack $requestStack, 
+          RouterInterface $router, 
+          $itemPerPage = 50
+    ) {
+        $this->itemPerPage = $itemPerPage;
+        $this->requestStack = $requestStack;
+        $this->router = $router;
+    }
+    
+    /**
+     * create a paginator instance
+     * 
+     * The default route and route parameters are the current ones. If set, 
+     * thos route are overriden.
+     * 
+     * @param int $totalItems
+     * @param string|null $route the specific route to use in pages
+     * @param array|null $routeParameters the specific route parameters to use in pages
+     * @return PaginatorInterface
+     */
+    public function create(
+          $totalItems, 
+          $route = null, 
+          array $routeParameters = null
+    ) {
+        
+        return new Paginator(
+              $totalItems,
+              $this->getCurrentItemPerPage(),
+              $this->getCurrentPageNumber(),
+              $route === null ? $this->getCurrentRoute() : $route,
+              $routeParameters === null ? $this->getCurrentRouteParameters() : 
+                 $routeParameters,
+              $this->router,
+              self::DEFAULT_CURRENT_PAGE_KEY,
+              self::DEFAULT_ITEM_PER_NUMBER_KEY);
+    }
+    
+    /**
+     * 
+     * @return int
+     */
+    public function getCurrentPageNumber()
+    {
+        return $this->requestStack
+              ->getCurrentRequest()
+              ->query
+              ->getInt(self::DEFAULT_CURRENT_PAGE_KEY, self::DEFAULT_PAGE_NUMBER);
+    }
+    
+    public function getCurrentItemPerPage()
+    {
+        return $this->requestStack
+              ->getCurrentRequest()
+              ->query
+              ->getInt(self::DEFAULT_ITEM_PER_NUMBER_KEY, $this->itemPerPage);
+    }
+    
+    public function getCurrentPageFirstItemNumber()
+    {
+        return ($this->getCurrentPageNumber() - 1) * 
+            $this->getCurrentItemPerPage();
+    }
+    
+    protected function getCurrentRoute()
+    {
+        $request = $this->requestStack->getCurrentRequest();
+        
+        return $request->get('_route');
+    }
+    
+    protected function getCurrentRouteParameters()
+    {
+        return array_merge(
+              $this->router->getContext()->getParameters(),
+              $this->requestStack->getCurrentRequest()
+                ->query->all());
+    }
+}

Pagination/PaginatorInterface.php

@@ -0,0 +1,130 @@
+<?php
+
+/*
+ * Chill is a software for social workers
+ * Copyright (C) 2016 Champs-Libres Coopérative <info@champs-libres.coop>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+namespace Chill\MainBundle\Pagination;
+
+/**
+ * Represent a set of numbered pages
+ * 
+ * Allow to calculate and render pagination for a set of pages.
+ * 
+ * The items are elements that `could` be shown. The item are divided and shown 
+ * into pages. Each page is numbered and count a given number of item per page. 
+ * 
+ * The first page number is 1, although the first result number is 0.
+ *
+ * @author Julien Fastré <julien.fastre@champs-libres.coop>
+ */
+interface PaginatorInterface extends \Countable
+{
+    /**
+     * get the number of result for this pagination
+     * 
+     * @return int
+     */
+    public function getTotalItems();
+    
+    /**
+     * get the first result for the current page
+     * 
+     * @return int
+     */
+    public function getCurrentPageFirstItemNumber();
+      
+    public function getItemPerPage();
+    
+    public function setItemPerPage($itemPerPage);
+    
+    /**
+     * get the number of page for this pagination.
+     * 
+     * @return int
+     */
+    public function countPages();
+    
+    /**
+     * get the current page
+     * 
+     * @return PageInterface
+     */
+    public function getCurrentPage();
+    
+    /**
+     * check if the given page is the current page
+     * 
+     * @param \Chill\MainBundle\Pagination\PageInterface $page
+     * @return bool
+     */
+    public function isCurrentPage(PageInterface $page);
+    
+    /**
+     * check if the page with the given number exists
+     * 
+     * @param int $number
+     */
+    public function hasPage($number);
+    
+    /**
+     * get page by his number
+     * 
+     * @param int $number
+     * @throws \RuntimeException if the pagination has no page with specified number
+     */
+    public function getPage($number);
+    
+    /**
+     * get the next page
+     * 
+     * @return PageInterface
+     * @throws \RuntimeException if the pagination has not next page
+     */
+    public function getNextPage();
+    
+    /**
+     * get the previous page
+     * 
+     * @return PageInterface
+     * @throws \RuntimeException if the pagination has not previous page
+     */
+    public function getPreviousPage();
+    
+    /**
+     * check if the current page has a next page
+     * 
+     * @return bool
+     */
+    public function hasNextPage();
+    
+    /**
+     * check if the current page has a page before
+     * 
+     * @return bool
+     */
+    public function hasPreviousPage();
+    
+    /**
+     * get a generator to generate pages
+     * 
+     * @return \Generator which return PageInterface elements
+     */
+    public function getPagesGenerator();
+    
+    
+}