Added basic Pager in order to support response pagination.

Author: vimishor

docs/examples/repositories.md

@@ -12,6 +12,9 @@ repositories:
 ### Prepare:
 {% include auth.md var_name="repositories" class_ns="Repositories" %}
 
+### Pagination:
+{% include pagination.md var_name="repositories" class_ns="Repositories" %}
+
 ### Get a list of repositories for an account:
 
 If the caller is properly authenticated and authorized, this method returns a collection containing public and private repositories.

lib/Bitbucket/API/Http/Response/Pager.php

@@ -0,0 +1,138 @@
+<?php
+/**
+ * This file is part of the bitbucket-api package.
+ *
+ * (c) Alexandru G. <alex@gentle.ro>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace Bitbucket\API\Http\Response;
+
+use Bitbucket\API\Http\ClientInterface;
+use Buzz\Message\MessageInterface;
+use Buzz\Message\Response;
+
+/**
+ * @author Alexandru Guzinschi <alex@gentle.ro>
+ */
+class Pager implements PagerInterface
+{
+    /** @var ClientInterface */
+    private $httpClient;
+
+    /** @var MessageInterface */
+    private $response;
+
+    /**
+     * @param ClientInterface  $httpClient
+     * @param MessageInterface $response
+     *
+     * @throws \UnexpectedValueException
+     */
+    public function __construct(ClientInterface $httpClient, MessageInterface $response)
+    {
+        /** @var Response $response */
+        if (!$response->isOk()) {
+            throw new \UnexpectedValueException("Can't paginate an unsuccessful response.");
+        }
+
+        $this->httpClient = $httpClient;
+        $this->response = $response;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function hasNext()
+    {
+        return array_key_exists('next', $this->getContent());
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function hasPrevious()
+    {
+        return array_key_exists('previous', $this->getContent());
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function fetchNext()
+    {
+        if ($this->hasNext()) {
+            $content = $this->getContent();
+            return $this->response = $this->httpClient->get($content['next']);
+        }
+
+        return null;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function fetchPrevious()
+    {
+        if ($this->hasPrevious()) {
+            $content = $this->getContent();
+            return $this->response = $this->httpClient->get($content['previous']);
+        }
+
+        return null;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function fetchAll()
+    {
+        $content = $this->getContent();
+        $values = [];
+
+        // merge all `values` and replace it inside the most recent response.
+        while (true) {
+            if (!array_key_exists('values', $content)) {
+                break;
+            }
+
+            $values = (0 === count($values)) ? $content['values'] : array_merge($values, $content['values']);
+
+            if (null !== ($next = $this->fetchNext())) {
+                $content = $this->getContent();
+                continue;
+            }
+
+            break;
+        }
+
+        $content['values'] = $values;
+        $this->response->setContent(json_encode($content));
+
+        return $this->response;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getCurrent()
+    {
+        return $this->response;
+    }
+
+    /**
+     * @access private
+     * @return array
+     */
+    private function getContent()
+    {
+        $content = json_decode($this->response->getContent(), true);
+
+        if (is_array($content) && JSON_ERROR_NONE === json_last_error()) {
+            return $content;
+        }
+
+        return [];
+    }
+}

lib/Bitbucket/API/Http/Response/PagerInterface.php

@@ -0,0 +1,62 @@
+<?php
+/**
+ * This file is part of the bitbucket-api package.
+ *
+ * (c) Alexandru G. <alex@gentle.ro>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace Bitbucket\API\Http\Response;
+
+use Buzz\Message\MessageInterface;
+
+/**
+ * @author Alexandru Guzinschi <alex@gentle.ro>
+ */
+interface PagerInterface
+{
+    /**
+     * @access public
+     * @return bool
+     */
+    public function hasNext();
+
+    /**
+     * @access public
+     * @return bool
+     */
+    public function hasPrevious();
+
+    /**
+     * Fetch next page and return http response
+     *
+     * @access public
+     * @return MessageInterface|null
+     */
+    public function fetchNext();
+
+    /**
+     * Fetch previous page and return http response
+     *
+     * @access public
+     * @return MessageInterface|null
+     */
+    public function fetchPrevious();
+
+    /**
+     * Fetch all available pages.
+     *
+     * @access public
+     * @return MessageInterface
+     */
+    public function fetchAll();
+
+    /**
+     * Get current http response.
+     *
+     * @access public
+     * @return MessageInterface
+     */
+    public function getCurrent();
+}