Add a ResultPager object to support pagination of all Api's

doc/index.md

@@ -18,6 +18,7 @@ APIs:
 
 Additional features:
 
+* [Pagination support](result_pager.md)
 * [Authentication & Security](security.md)
 * [Request any Route](request_any_route.md)
 * [Customize `php-github-api` and testing](customize.md)

doc/result_pager.md

@@ -0,0 +1,44 @@
+## Result Pager
+[Back to the navigation](index.md)
+
+### Usage examples
+
+Get all repositories of a organization
+
+```php
+$client = new Github\Client();
+
+$organizationApi = $client->api('organization');
+
+$paginator = new Github\ResultPager( $client );
+$result    = $paginator->fetchAll( $organizationApi, 'repositories', 'github );
+```
+
+Get the first page
+```php
+$client = new Github\Client();
+
+$organizationApi = $client->api('organization');
+
+$paginator = new Github\ResultPager( $client );
+$result    = $paginator->fetch( $organizationApi, 'repositories', 'github );
+```
+Check for a next page:
+```php
+$paginator->hasNext();
+```
+
+Get next page:
+```php
+$paginator->fetchNext();
+```
+
+Check for pervious page:
+```php
+$paginator->getPrevious();
+```
+
+Get prevrious page:
+```php
+$paginator->fetchPrevious();
+```

lib/Github/Api/AbstractApi.php

@@ -18,6 +18,13 @@ abstract class AbstractApi implements ApiInterface
      */
     protected $client;
 
+    /**
+     * number of items per page (GitHub pagination)
+     *
+     * @var int
+     */
+    protected $perPage = null;
+
     /**
      * @param Client $client
      */
@@ -30,11 +37,31 @@ public function configure()
     {
     }
 
+    /**
+     * @return int|null
+     */
+    public function getPerPage()
+    {
+        return $this->perPage;
+    }
+
+    /**
+     * @param Client $client
+     */
+    public function setPerPage($perPage)
+    {
+        $this->perPage = (int) $perPage;
+        return $this;
+    }
+
     /**
      * {@inheritDoc}
      */
     protected function get($path, array $parameters = array(), $requestHeaders = array())
     {
+        if (null !== $this->perPage && !isset($parameters['per_page'])) {
+            $parameters['per_page'] = $this->perPage;
+        }
         $response = $this->client->getHttpClient()->get($path, $parameters, $requestHeaders);
 
         return $response->getContent();

lib/Github/HttpClient/HttpClient.php

@@ -163,7 +163,9 @@ public function put($path, array $parameters = array(), array $headers = array()
      */
     public function request($path, array $parameters = array(), $httpMethod = 'GET', array $headers = array())
     {
-        $path = trim($this->options['base_url'].$path, '/');
+        if ( !empty($this->options['base_url']) AND 0 !== strpos( $path, $this->options['base_url'] )) {
+            $path = trim($this->options['base_url'].$path, '/');
+        }
 
         $request = $this->createRequest($httpMethod, $path);
         $request->addHeaders($headers);

lib/Github/ResultPager.php

@@ -0,0 +1,157 @@
+<?php
+
+namespace Github;
+
+use Github\Api\ApiInterface;
+use Github\Exception\InvalidArgumentException;
+use Github\HttpClient\HttpClient;
+use Github\HttpClient\HttpClientInterface;
+
+/**
+ * Pager class for supporting pagination in github classes
+ *
+ * @author Ramon de la Fuente <ramon@future500.nl>
+ * @author Mitchel Verschoof <mitchel@future500.nl>
+ */
+class ResultPager implements ResultPagerInterface
+{
+    /**
+     * @var Github\Client client
+     */
+    protected $client;
+
+    /**
+     * @var array pagination
+     * Comes from pagination headers in Github API results
+     */
+    protected $pagination = null;
+
+    public function __construct( Client $client )
+    {
+        $this->client = $client;
+    }
+
+    /**
+     *  @return null|array pagination result of last request
+     */
+    public function getPagination()
+    {
+        return $this->pagination;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function fetch( ApiInterface $api, $method )
+    {
+        $parameters = array_slice(func_get_args(),2);
+
+        $result = call_user_func_array(array($api, $method), $parameters);
+        $this->postFetch();
+
+        return $result;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchAll( ApiInterface $api, $method )
+    {
+        $parameters = array_slice(func_get_args(),2);
+
+        // Set parameters per_page to GitHub max to minimize number of requests
+        $api->setPerPage(100);
+
+        $result = array();
+        $result = call_user_func_array(array($api, $method), $parameters);
+        $this->postFetch();
+
+        while ($this->hasNext()) {
+            $result = array_merge($result, $this->fetchNext());
+        }
+
+        return $result;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function postFetch()
+    {
+        $this->pagination = $this->client->getHttpClient()->getLastResponse()->getPagination();
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function hasNext()
+    {
+        return $this->has('next');
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchNext()
+    {
+        return $this->get('next');
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function hasPrevious()
+    {
+        return $this->has('prev');
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchPrevious()
+    {
+        return $this->get('prev');
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchFirst()
+    {
+        return $this->get('first');
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchLast()
+    {
+        return $this->get('last');
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    protected function has($key)
+    {
+        if (!empty($this->pagination) and isset($this->pagination[$key])) {
+            return true;
+        }
+
+        return false;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    protected function get($key)
+    {
+        if ( $this->has($key) ) {
+            $result = $this->client->getHttpClient()->get($this->pagination[$key]);
+            $this->postFetch();
+
+            return $result->getContent();
+        }
+    }
+
+}

lib/Github/ResultPagerInterface.php

@@ -0,0 +1,66 @@
+<?php
+
+namespace Github;
+
+use Github\Api\ApiInterface;
+
+/**
+ * Pager interface
+ *
+ * @author Ramon de la Fuente <ramon@future500.nl>
+ * @author Mitchel Verschoof <mitchel@future500.nl>
+ */
+interface ResultPagerInterface
+{
+    /**
+     * Fetch a single result (page) from an api call
+     */
+    public function fetch( ApiInterface $api, $method );
+
+    /**
+     * Fetch all results (pages) from an api call
+     * Use with care - there is no maximum
+     */
+    public function fetchAll( ApiInterface $api, $method );
+
+    /**
+     * Method that performs the actual work to refresh the pagination property
+     */
+    public function postFetch();
+
+    /**
+     * Check to determine the availability of a next page
+     * @return bool
+     */
+    public function hasNext();
+
+    /**
+     * Check to determine the availability of a previous page
+     * @return bool
+     */
+    public function hasPrevious();
+
+    /**
+     * Fetch the next page
+     * @return array
+     */
+    public function fetchNext();
+
+    /**
+     * Fetch the previous page
+     * @return array
+     */
+    public function fetchPrevious();
+
+    /**
+     * Fetch the first page
+     * @return array
+     */
+    public function fetchFirst();
+
+    /**
+     * Fetch the last page
+     * @return array
+     */
+    public function fetchLast();
+}

test/Github/Tests/Mock/TestResponse.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace Github\Tests\Mock;
+
+class TestResponse
+{
+    protected $loopCount;
+
+    protected $content;
+
+    public function __construct( $loopCount, array $content = array() )
+    {
+        $this->loopCount = $loopCount;
+        $this->content   = $content;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getContent()
+    {
+        return $this->content;
+    }
+
+    /**
+     * @return array|null
+     */
+    public function getPagination()
+    {
+        if($this->loopCount){
+            $returnArray = array(
+                'next' => 'http://github.com/' . $this->loopCount
+            );
+        } else {
+            $returnArray = array(
+                'prev' => 'http://github.com/prev'
+            );
+        }
+
+        $this->loopCount--;
+
+        return $returnArray;
+    }
+}