Merge pull request #2 from zf-fr/cursor-pagination

Cursor pagination

CHANGELOG.md

@@ -1,3 +1,9 @@
+# 1.5.0
+
+* [BC] Update latest API descriptor to 2014-03-28. This adds support for the new cursor-based pagination. This version
+removes the "offset" parameter, in favour of a new "starting_after" parameter. The new "limit" parameter is equivalent
+to the old "count" parameter. If you use ZfrStripe iterators, this does not change anything for you.
+
 # 1.4.0
 
 * [BC] Update latest API descriptor to 2014-03-13. This adds a new "statement_description" for both creating charge and

README.md

@@ -32,11 +32,11 @@ $client = new StripeClient('my-api-key');
 > You can change the API key for the client using the `setApiKey` method. This is useful if you are using Stripe
 Connect and make both your own API calls and API calls on behalf of your users.
 
-The currently latest supported version of the API is 2014-03-13. You can (and should) also explicitly specify the version
+The currently latest supported version of the API is 2014-03-28. You can (and should) also explicitly specify the version
 of the client using the second parameter:
 
 ```php
-$client = new StripeClient('my-api-key', '2014-03-13');
+$client = new StripeClient('my-api-key', '2014-03-28');
 ```
 
 ### Versioning
@@ -111,6 +111,22 @@ foreach ($iterator as $event) {
 }
 ```
 
+> Note: starting from 2014-03-28 version, Stripe has changed how it handles pagination, and now uses a cursor-based
+pagination. This is much more flexible, as it allows you to keep track of your pagination, even if new items were
+added while you paginate data. Furthermore, it has a new property that allows us to avoid doing an additional request
+at the end to check if there are more data to fetch:
+
+```php
+$iterator = $client->getInvoicesIterator(['starting_after' => 'in_abcdef');
+
+foreach ($iterator as $invoices) {
+    // Do something
+}
+```
+
+ZfrStripe takes care of fetching the last item in the batch, extracting the id, and continuing doing requests
+until no more data is available!
+
 ### Exceptions
 
 ZfrStripe tries its best to throw useful exceptions. Two kinds of exceptions can occur:

src/ZfrStripe/Client/Iterator/StripeCommandsCursorIterator.php

@@ -0,0 +1,65 @@
+<?php
+/*
+ * 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 MIT license.
+ */
+
+namespace ZfrStripe\Client\Iterator;
+
+use Guzzle\Service\Command\CommandInterface;
+use Guzzle\Service\Resource\ResourceIterator;
+
+/**
+ * Basic iterator that is used to iterate over all Stripe commands
+ *
+ * This is used for the new (introduced in 2014-03-28) cursor-based pagination
+ *
+ * @author  Michaël Gallego <[email protected]>
+ * @licence MIT
+ */
+class StripeCommandsCursorIterator extends ResourceIterator
+{
+    /**
+     * @param CommandInterface $command
+     * @param array            $data
+     */
+    public function __construct(CommandInterface $command, array $data = array())
+    {
+        parent::__construct($command, $data);
+
+        $this->pageSize = 100; // This is the maximum allowed by Stripe
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    protected function sendRequest()
+    {
+        $this->command->set('limit', $this->pageSize);
+
+        if ($this->nextToken) {
+            $this->command->set('starting_after', $this->nextToken);
+        }
+
+        $result   = $this->command->execute();
+        $data     = $result['data'];
+        $lastItem = end($data);
+
+        // This avoid to do any additional request
+        $this->nextToken = $result['has_more'] ? $lastItem['id'] : false;
+
+        return $data;
+    }
+}

src/ZfrStripe/Client/ServiceDescription/Stripe-2014-03-13.php

@@ -53,7 +53,7 @@
 
 return array(
     'name'        => 'Stripe',
-    'apiVersion'  => '2014-01-31',
+    'apiVersion'  => '2014-03-13',
     'baseUrl'     => 'https://api.stripe.com',
     'description' => 'Stripe is a payment system',
     'operations'  => array(