add support for cursor based pagination

.github/workflows/test.yml

@@ -10,7 +10,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        php-versions: ['7.4', '8.0', '8.1']
+        php-versions: ['8.0', '8.1', '8.2']
         phpunit-versions: ['9.6']
     steps:
       - uses: actions/checkout@v2
@@ -70,7 +70,7 @@ jobs:
         env:
           CC_TEST_REPORTER_ID: ${{ secrets.CC_TEST_REPORTER_ID }}
         if: |
-            matrix.php-versions == '7.4' && success() && 
+            matrix.php-versions == '8.0' && success() &&
             github.event.pull_request.head.repo.full_name == 'chartmogul/chartmogul-php'
         run: ./cc-test-reporter after-build
 
@@ -84,7 +84,7 @@ jobs:
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '7.4'
+          php-version: '8.0'
           tools: cs2pr, php-cs-fixer
 
       - name: "Run php-cs-fixer"
@@ -99,7 +99,7 @@ jobs:
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '7.4'
+          php-version: '8.0'
           tools: phpstan, cs2pr
 
       - name: Install dependencies

6.0-Upgrade.md

@@ -0,0 +1,31 @@
+# Upgrading to chartmogul-php 6.0.0
+
+This new version replaces the existing pagination for the `::all()` endpoints that used a combination of `page` and `per_page` parameters, and instead uses a `cursor` based pagination. So to list (as an example) Plans you now can:
+
+```php
+$plans = ChartMogul\Plan::all([
+    "per_page" => 1
+]);
+
+// This will return an array of plans (if available), and a cursor + has_more fields
+{
+    "plans" => [
+        {
+            "uuid" => "some_uuid",
+            "data_source_uuid" => "some_uuid",
+            "name" => "Master Plan"
+        }
+    ],
+    "has_more" => true,
+    "cursor" => "MjAyMy0wNy0yOFQwODowOToyMi4xNTQyMDMwMDBaJjk0NDQ0Mg=="
+}
+
+if ($plans->has_more) {
+  $more_plans = ChartMogul\Plan::all([
+      "per_page" => 1,
+      "cursor" => $plans->cursor
+  ]);
+}
+```
+
+If you have existing code that relies on the `page` parameter, those requests will throw an error now alerting you of their deprecation.

CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog],
+and this project adheres to [Semantic Versioning].
+
+[Keep a Changelog]: https://keepachangelog.com/en/1.0.0/
+[Semantic Versioning]: https://semver.org/spec/v2.0.0.html
+
+## [6.0.0] - 2023-09-18
+
+### Added
+- Support for cursor based pagination to `::all()` endpoints.
+- Changelog and 6.0.0 upgrade instructions.
+- PHP 8.2 support #112
+
+### Fixed
+- Undefined constant `ChartMogul\DEFAULT_MAX_RETRIES` #112
+
+### Removed
+- Support for PHP 7.x as 7.4 reached EOL in 2022.

Dockerfile

@@ -5,10 +5,7 @@ RUN mv composer.phar /usr/local/bin/composer
 RUN chmod a+x /usr/local/bin/composer
 RUN apt-get update && apt-get  install -y git unzip
 ARG VERSION
-RUN if [ "$VERSION" = "7.4" ]; then \
-        composer global require phpunit/phpunit:^8 && \
-        pecl install xdebug-2.9.8; \
-    elif [ "$VERSION" = "8.0" ]; then \
+RUN if [ "$VERSION" = "8.0" ]; then \
         composer global require phpunit/phpunit:^9 && \
         pecl install xdebug-3.0.0; \
     elif [ "$VERSION" = "8.1" ]; then \

Makefile

@@ -3,7 +3,6 @@ RUNNER=docker run -it --rm --workdir "/src" -v "$(PWD):/src" -v "$(HOME)/.compos
 .PHONY: build composer php
 
 build:
-	@docker build --build-arg VERSION=7.4 --tag=chartmogulphp74 .
 	@docker build --build-arg VERSION=8.0 --tag=chartmogulphp80 .
 	@docker build --build-arg VERSION=8.1 --tag=chartmogulphp81 .
 	@docker build --build-arg VERSION=8.2 --tag=chartmogulphp82 .

README.md

@@ -29,11 +29,11 @@
 
 ## Installation
 
-This library requires php 5.5 or above.
+This library requires php `8.0` or above.
 
 For older php versions (`< 7.4`) use `1.x.x` releases of this library.
 
-For php version `>=7.4` use the latest releases (`5.x.x`) of the library
+For php version `>=7.4` but `< 8.0` use the `5.x.x` releases of the library.
 
 
 The library doesn't depend on any concrete HTTP client libraries. Follow the instructions [here](http://docs.php-http.org/en/latest/httplug/users.html) to find out how to include a HTTP client.
@@ -134,7 +134,6 @@ ChartMogul\Customer::create([
 
 ```php
 ChartMogul\Customer::all([
-  'page' => 1,
   'data_source_uuid' => $ds->uuid
 ]);
 ```
@@ -305,7 +304,7 @@ $tags = $customer->removeCustomAttributes("age", "channel");
 ```php
 $customer = ChartMogul\Customer::retrieve($uuid);
 $contacts = $customer->contacts([
-  'cursor' => 'aabbccdd...'
+  'cursor' => 'cursor=='
 ]);
 ```
 
@@ -326,7 +325,7 @@ $new_customer = $customer->createContact([
 
 ```php
 $contacts = ChartMogul\Contacts::all([
-  'cursor' => 'aabbccdd...'
+  'cursor' => 'cursor=='
 ]);
 ```
 
@@ -394,7 +393,7 @@ ChartMogul\Plan::retrieve($uuid);
 
 ```php
 $plans = ChartMogul\Plan::all([
-  'page' => 1
+  'per_page' => 1
 ]);
 ```
 
@@ -481,7 +480,7 @@ ChartMogul\PlanGroup::retrieve($uuid);
 
 ```php
 $plan_groups = ChartMogul\PlanGroup::all([
-  'page' => 1
+  'per_page' => 10
 ]);
 ```
 
@@ -571,8 +570,8 @@ $ci = ChartMogul\CustomerInvoices::create([
 ```php
 $ci = ChartMogul\CustomerInvoices::all([
     'customer_uuid' => $cus->uuid,
-    'page' => 1,
-    'per_page' => 200
+    'per_page' => 200,
+    'cursor' => 'cursor=='
 ]);
 ```
 
@@ -581,8 +580,8 @@ $ci = ChartMogul\CustomerInvoices::all([
 ```php
 $invoices = ChartMogul\Invoice::all([
     'external_id' => 'my_invoice',
-    'page' => 1,
-    'per_page' => 200
+    'per_page' => 200,
+    'cursor' => 'cursor=='
 ]);
 ```
 
@@ -785,6 +784,7 @@ The library throws following Exceptions:
 - `ChartMogul\Exceptions\NotFoundException`
 - `ChartMogul\Exceptions\ResourceInvalidException`
 - `ChartMogul\Exceptions\SchemaInvalidException`
+- `ChartMogul\Exceptions\InvalidParamException`
 
 The following table describes the public methods of the error object.
 

composer.json

@@ -25,7 +25,7 @@
         }
     },
     "require": {
-        "php": ">=7.1",
+        "php": ">=8.0",
         "psr/http-message": "^1.0 || ^2.0",
         "psr/http-client-implementation": "^1.0",
         "doctrine/collections": "^1.6 || ^2.0",

phpstan.neon

@@ -4,3 +4,4 @@ parameters:
    - src
   ignoreErrors:
    - '#Unsafe usage of new static\(\).#'
+  treatPhpDocTypesAsCertain: false

src/Customer.php

@@ -3,7 +3,6 @@
 namespace ChartMogul;
 
 use ChartMogul\Resource\AbstractResource;
-use ChartMogul\Resource\Collection;
 use ChartMogul\Resource\CollectionWithCursor;
 use ChartMogul\Http\ClientInterface;
 use ChartMogul\Service\UpdateTrait;
@@ -115,7 +114,7 @@ public static function findByExternalId($externalId, ClientInterface $client = n
         $response = self::all($externalId, $client);
 
         if (
-            $response instanceof Collection
+            $response instanceof CollectionWithCursor
             && !$response->isEmpty()
         ) {
             return $response->first();
@@ -128,7 +127,7 @@ public static function findByExternalId($externalId, ClientInterface $client = n
      * Search for Customers
      * @param  string                $email
      * @param  ClientInterface|null $client
-     * @return Collection|static
+     * @return CollectionWithCursor|static
      */
     public static function search($email, ClientInterface $client = null)
     {
@@ -265,7 +264,7 @@ public function updateCustomAttributes($custom)
     /**
      * Find a Customer Subscriptions
      * @param  array  $options
-     * @return Collection | Customer
+     * @return CollectionWithCursor | Customer
      * @deprecated Use Import\Subscription.
      */
     public function subscriptions(array $options = [])
@@ -280,7 +279,7 @@ public function subscriptions(array $options = [])
     /**
      * Find customer's invoices
      * @param  array  $options
-     * @return Collection | Customer
+     * @return CollectionWithCursor | Customer
      * @deprecated Use Import\CustomerInvoices.
      */
     public function invoices(array $options = [])

src/Customers.php

@@ -3,7 +3,7 @@
 namespace ChartMogul;
 
 use ChartMogul\Resource\AbstractResource;
-use ChartMogul\Resource\Collection;
+use ChartMogul\Resource\CollectionWithCursor;
 use ChartMogul\Http\ClientInterface;
 use ChartMogul\Resource\EntryTrait;
 use ChartMogul\Service\AllTrait;
@@ -56,7 +56,7 @@ public function __construct(array $attr = [], ClientInterface $client = null)
      * Search for Customers
      * @param  string                $email
      * @param  ClientInterface|null $client
-     * @return Collection|static
+     * @return CollectionWithCursor|static
      * @deprecated Use Customer.
      */
     public static function search($email, ClientInterface $client = null)

src/Exceptions/InvalidParamException.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace ChartMogul\Exceptions;
+
+/**
+ * InvalidParamException
+ * @codeCoverageIgnore
+ */
+class InvalidParamException extends ChartMogulException
+{
+}

src/Http/Client.php

@@ -30,7 +30,7 @@ class Client implements ClientInterface
     /**
     * @var string
     */
-    private $apiVersion = '5.1.1';
+    private $apiVersion = '6.0.0';
 
     /**
     * @var string
@@ -163,6 +163,12 @@ public function send($path = '', $method = 'GET', $data = [])
     {
         $query = '';
         if ($method === 'GET') {
+            if (array_key_exists('page', $data)) {
+                throw new \ChartMogul\Exceptions\InvalidParamException(
+                    "'page' parameter is deprecated."
+                );
+            }
+
             $query = http_build_query($data);
             $data = [];
         }

src/Http/Retry.php

@@ -44,7 +44,7 @@ public function retry($callback)
         if ($this->retries === 0) {
             return $callback();
         }
-        $backoff = new Backoff($this->retries, new ExponentialStrategy(), 60*1000, true);
+        $backoff = new Backoff($this->retries, new ExponentialStrategy(), 60 * 1000, true);
         $backoff->setDecider($this);
         return $backoff->run($callback);
     }

src/Resource/AbstractResource.php

@@ -67,73 +67,21 @@ public function setClient(ClientInterface $client)
     /**
      * @param array $data
      * @param ClientInterface|null $client
-     * @return Collection|static
+     * @return CollectionWithCursor|static
      */
     public static function fromArray(array $data, ClientInterface $client = null)
     {
         if (isset($data[static::ROOT_KEY])) {
-            if (static::ROOT_KEY != "subscription_events") {
-                $array = new Collection(array_map(function ($data) use ($client) {
-                    return static::fromArray($data, $client);
-                }, $data[static::ROOT_KEY]));
-                // The following are subject to change soon, so they are optional.
-                $array = static::allData($data, $array);
-            } else {
-                $array = new SubscriptionEventCollection(array_map(function ($data) use ($client) {
-                    return static::fromArray($data, $client);
-                }, $data[static::ROOT_KEY]));
+            $array = new CollectionWithCursor(array_map(function ($data) use ($client) {
+                return static::fromArray($data, $client);
+            }, $data[static::ROOT_KEY]));
 
-                if (isset($data["meta"])) {
-                    $meta = $data['meta'];
-                    $array->meta = static::metaData($meta);
-                }
-            }
-            return $array;
-        }
-
-        return new static($data, $client);
-    }
-
-    public static function allData(array $data, Collection $array)
-    {
-        if (isset($data["current_page"])) {
-            $array->current_page = $data["current_page"];
-        }
-        if (isset($data["total_pages"])) {
-            $array->total_pages = $data["total_pages"];
-        }
-        if (isset($data["has_more"])) {
+            $array->cursor = $data["cursor"];
             $array->has_more = $data["has_more"];
-        }
-        if (isset($data["per_page"])) {
-            $array->per_page = $data["per_page"];
-        }
-        if (isset($data["page"])) {
-            $array->page = $data["page"];
-        }
-
-        return $array;
-    }
 
-    public static function metaData(array $meta)
-    {
-        $array_meta = new MetaCollection();
-        if (isset($meta['page'])) {
-            $array_meta->page = $meta["page"];
-        }
-        if (isset($meta['next_key'])) {
-            $array_meta->next_key = $meta["next_key"];
-        }
-        if (isset($meta['prev_key'])) {
-            $array_meta->prev_key = $meta["prev_key"];
-        }
-        if (isset($meta['before_key'])) {
-            $array_meta->before_key = $meta["before_key"];
-        }
-        if (isset($meta['total_pages'])) {
-            $array_meta->total_pages = $meta["total_pages"];
+            return $array;
+        } else {
+            return new static($data, $client);
         }
-
-        return $array_meta;
     }
 }