Add iterator feature

CHANGELOG.md

@@ -1,3 +1,7 @@
+# 1.2.0
+
+* Add iterators
+
 # 1.1.0
 
 * Allow to reuse the same client with different API keys (useful when dealing with Stripe Connect)

README.md

@@ -66,6 +66,34 @@ $details = $client->getCharges(array(
 ));
 ```
 
+#### Iterators
+
+You may want to retrieve a list of customers, events or charges. Instead of manually doing all the request yourself,
+you can use iterators. ZfrStripe provides iterators for all iterable resources:
+
+```php
+$iterator = $client->getCustomersIterator();
+
+foreach ($iterator as $user) {
+    // Do something
+}
+```
+
+By default, ZfrStripe retrieves 100 elements per API call (which is the maximum allowed by Stripe API). You may want
+to lower this limit by using the `setPageSize` method. You can also set a upper bound of how many results you want
+to retrieve by using the `setLimit` method.
+
+Finally, you can still use API parameters when using an iterator. For instance, this will retrieve all the events
+that have the event `customer.subscription.updated`:
+
+```php
+$iterator = $client->getEventsIterator(array('type' => 'customer.subscription.updated'));
+
+foreach ($iterator as $event) {
+    // Do something
+}
+```
+
 ### Exceptions
 
 ZfrStripe tries its best to throw useful exceptions. Two kinds of exceptions can occur:

src/ZfrStripe/Client/Iterator/StripeCommandsIterator.php

@@ -0,0 +1,58 @@
+<?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
+ *
+ * @author  Michaël Gallego <[email protected]>
+ * @licence MIT
+ */
+class StripeCommandsIterator 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('count', $this->pageSize);
+        $this->command->set('offset', $this->iteratedCount);
+
+        $result = $this->command->execute();
+        $users  = $result['data'];
+
+        $this->nextToken = empty($users) ? false : true;
+
+        return $users;
+    }
+}

src/ZfrStripe/Client/StripeClient.php

@@ -22,6 +22,8 @@
 use Guzzle\Plugin\ErrorResponse\ErrorResponsePlugin;
 use Guzzle\Service\Client;
 use Guzzle\Service\Description\ServiceDescription;
+use Guzzle\Service\Resource\ResourceIterator;
+use ZfrStripe\Client\Iterator\StripeCommandsIterator;
 use ZfrStripe\Http\QueryAggregator\StripeQueryAggregator;
 
 /**
@@ -136,6 +138,20 @@
  * ACCOUNT RELATED METHODS:
  *
  * @method array getAccount(array $args = array()) {@command Stripe GetAccount}
+ *
+ * ITERATOR METHODS:
+ *
+ * @method ResourceIterator getCustomersIterator()
+ * @method ResourceIterator getChargesIterator()
+ * @method ResourceIterator getCardsIterator()
+ * @method ResourceIterator getPlansIterator()
+ * @method ResourceIterator getCouponsIterator()
+ * @method ResourceIterator getInvoicesIterator()
+ * @method ResourceIterator getInvoiceItemsIterator()
+ * @method ResourceIterator getTransfersIterator()
+ * @method ResourceIterator getRecipientsIterator()
+ * @method ResourceIterator getApplicationFeesIterator()
+ * @method ResourceIterator getEventsIterator()
  */
 class StripeClient extends Client
 {
@@ -203,6 +219,15 @@ public function getApiKey()
      */
     public function __call($method, $args = array())
     {
+        if (substr($method, -8) === 'Iterator') {
+            // Allow magic method calls for iterators (e.g. $client-><CommandName>Iterator($params))
+            $commandOptions  = isset($args[0]) ? $args[0] : array();
+            $iteratorOptions = isset($args[1]) ? $args[1] : array();
+            $command         = $this->getCommand(substr($method, 0, -8), $commandOptions);
+
+            return new StripeCommandsIterator($command, $iteratorOptions);
+        }
+
         return parent::__call(ucfirst($method), $args);
     }