Merge pull request #10 from exonet/tsi/EXO-4666

Add links navigation and getRecursive

.styleci.yml

@@ -1,9 +1,5 @@
 preset: recommended
 
-enabled:
-  - strict
-  - strict_param
-
 disabled:
-  - align_double_arrow
-  - simplified_null_return
+    - align_double_arrow
+

.travis.yml

@@ -1,14 +1,21 @@
 language: php
 
-php:
-    - 7.1
-    - 7.2
-    - 7.3
+services:
+    - docker
 
 cache:
     directories:
         - vendor
         - $HOME/.composer/cache
 
+before_install:
+    - docker pull php:7.1-cli
+    - docker pull php:7.2-cli
+    - docker pull php:7.3-cli
+    - docker pull php:7.4-cli
+
 install:
     - composer install
+
+script:
+    - ./run-tests.sh

CHANGELOG.md

@@ -5,7 +5,14 @@ All notable changes to `exonet-api-php` will be documented in this file.
 Updates should follow the [Keep a CHANGELOG](http://keepachangelog.com/) principles.
 
 ## Unreleased
-[Compare v2.2.0 - Unreleased](https://github.com/exonet/exonet-api-php/compare/v2.2.0...master)
+[Compare v2.3.0 - Unreleased](https://github.com/exonet/exonet-api-php/compare/v2.3.0...master)
+
+## [v2.3.0](https://github.com/exonet/exonet-api-php/releases/tag/v2.3.0) - 2020-08-07
+[Compare v2.2.0 - v2.3.0](https://github.com/exonet/exonet-api-php/compare/v2.2.0...v2.3.0)
+### Added
+- Add the `total()` method to resource sets to get the total number of resources (and not only the number of resources in the current resource set).
+- Add `nextPage`, `previousPage`, `firstPage` and `lastPage` methods to the `ApiResourceSet` for easy loading of paginated resource sets.
+- Add a `getRecursive` method to the `Request` to get the resource set including recursively the resource sets from the following pages.
 
 ## [v2.2.0](https://github.com/exonet/exonet-api-php/releases/tag/v2.2.0) - 2019-11-19
 [Compare v2.1.1 - v2.2.0](https://github.com/exonet/exonet-api-php/compare/v2.1.1...v2.2.0)

docs/api_responses.md

@@ -1,5 +1,5 @@
 # Using API Responses
-There are two types of API responses upon a successful request. If a single resource is requested then an [`ApiResource`](api_resources.md) is 
+There are two types of API responses upon a successful request. If a single resource is requested then an [`ApiResource`](api_resources.md) is
 returned, if multiple resources are requested then an `ApiResourceSet` is returned.
 
 ## The `ApiResourceSet` class
@@ -16,6 +16,29 @@ foreach ($certificates as $certificate) {
 }
 ```
 
+The get the number of items in a resource set, you can use one of the following methods:
+```php
+$certificates->count(); // Returns the number of resources in the current resource set.
+$certificates->total(); // Returns the total number of resources in the resource set, ignoring pagination.
+```
+
+If `count != total` you can get the next/previous/first/last page by calling one of the pagination methods:
+```php
+// Get the next resource set:
+$certificates->nextPage();
+
+// Get the previous resource set:
+$certificates->previousPage();
+
+// Get the first resource set:
+$certificates->firstPage();
+
+// Get the last resource set:
+$certificates->lastPage();
+```
+
+Each of this methods will return `null` if not available.
+
 ## The [`ApiResource`](api_resources.md) class
 Each resource returned by the API is transformed to an [`ApiResource`](api_resources.md) instance. This makes it possible to have easy access
 to the attributes, resourceType and ID of the resource. Each of these fields can be accessed as if it is a property on the class:

docs/calls.md

@@ -1,5 +1,5 @@
 # Making API calls
-After the client has been initialised, use the `resource` method to define which type of resource you want to get from 
+After the client has been initialised, use the `resource` method to define which type of resource you want to get from
 the API:
 
 ```php
@@ -24,6 +24,19 @@ After setting the parameters you can call the `->get()` method to retrieve the r
 $certificates = $certificatesRequest->get();
 ```
 
+It is also possible to get all resource sets recursively. The package will check the URL defined in `links.next` and as
+long as the value is not `null` it will make an additional request and merge the results:
+
+```php
+$certificates = $certificatesRequest->getRecursive();
+```
+
+Please note that the `getRecursive` method respects pagination and filters. So the following example will get all
+non-expired certificates, starting from page two in batches of ten:
+```php
+$certificates = $certificatesRequest->filter('expired', false)->page(2)->size(10)->getRecursive();
+```
+
 ## Getting a single resource by ID
 If you want to get a specific resource by its ID, use the `id()` method to define specify the ID of the resource:
 ```php

examples/dns_record_post.php

@@ -21,7 +21,7 @@
 // Show this message when there are no zones.
 if (empty($zones)) {
     echo 'There are no zones available.';
-    die();
+    exit();
 }
 $zone = $zones[0];
 

examples/dns_zone_details.php

@@ -19,7 +19,7 @@
 // Show this message when there are no zones.
 if (empty($zones)) {
     echo 'There are no zones available.';
-    die();
+    exit();
 }
 $zone = $zones[0];
 

examples/ticket_details.php

@@ -20,7 +20,7 @@
 // Show this message when there are no tickets available.
 if (empty($tickets)) {
     echo 'There are no tickets available';
-    die();
+    exit();
 }
 
 $ticket = $tickets[0];

examples/tickets.php

@@ -25,7 +25,7 @@
  * @param string         $description The description of the list.
  * @param ApiResourceSet $ticketList  The resource set containing ticket resources.
  */
-function renderTickets(string $description, ApiResourceSet $ticketList) : void
+function renderTickets(string $description, ApiResourceSet $ticketList): void
 {
     echo sprintf("\n%s (%d)\n%s\n", $description, count($ticketList), str_repeat('-', strlen($description)));
 

run-tests.sh

@@ -0,0 +1,55 @@
+bold=$(tput bold)
+red=$(tput setaf 1)
+green=$(tput setaf 2)
+normal=$(tput sgr0)
+RESULTS=""
+HAS_FAILED_TESTS=0
+
+function run() {
+    PHP_VERSION=$1
+
+    echo ""
+    echo "--------------------------------------------"
+    echo "Testing with PHP ${bold}$PHP_VERSION${normal}"
+    echo "--------------------------------------------"
+
+    docker run \
+        -it \
+        --rm \
+        --name php"$PHP_VERSION" \
+        -v "$PWD":/usr/src \
+        -w /usr/src/ \
+        php:"$PHP_VERSION"-cli \
+        php ./vendor/bin/phpunit
+
+    if [ $? -eq 0 ]; then
+        RESULTS="$RESULTS\n${green}✓ PHP $PHP_VERSION${normal}"
+    else
+        HAS_FAILED_TESTS=1
+        RESULTS="$RESULTS\n${red}𐄂 PHP $PHP_VERSION${normal}"
+    fi
+
+    echo "(PHP $PHP_VERSION)"
+}
+
+# Get the arguments from the call (i.e. ./run-tests.sh 7.4)
+SET_PHP_VERSION=$1
+
+# If an arguments is given, only run that version.
+if [ "$#" -eq 1 ]; then
+    run "$SET_PHP_VERSION"
+else
+    # Run tests for different PHP 7 versions.
+    for phpversion in {1..4}; do
+        run "7.$phpversion"
+        RESULTS="$RESULTS\n"
+    done
+fi
+
+echo ""
+echo "RESULTS"
+echo "----------------------"
+printf "$RESULTS"
+
+exit $HAS_FAILED_TESTS
+

src/Auth/AbstractAuth.php

@@ -19,7 +19,7 @@ abstract class AbstractAuth
      *
      * @return string The access token.
      */
-    public function getToken() : string
+    public function getToken(): string
     {
         return $this->token;
     }
@@ -29,7 +29,7 @@ public function getToken() : string
      *
      * @param string $token The access token.
      */
-    public function setToken(string $token) : void
+    public function setToken(string $token): void
     {
         $this->token = $token;
     }

src/Client.php

@@ -19,7 +19,7 @@ class Client implements LoggerAwareInterface
     /**
      * The version of this package. Used in the user-agent header.
      */
-    public const CLIENT_VERSION = 'v1.0.0';
+    public const CLIENT_VERSION = 'v2.3.0';
 
     /**
      * The API base URL.
@@ -75,7 +75,7 @@ public function __construct(?AbstractAuth $auth = null, ?string $apiUrl = null)
      *
      * @return Client The cache instance.
      */
-    public static function getInstance() : self
+    public static function getInstance(): self
     {
         if (!isset(self::$_instance)) {
             self::$_instance = new self();
@@ -91,7 +91,7 @@ public static function getInstance() : self
      *
      * @return AbstractAuth The auth instance.
      */
-    public function getAuth() : AbstractAuth
+    public function getAuth(): AbstractAuth
     {
         if ($this->auth === null) {
             $this->log()->error('No authentication method set.');
@@ -109,7 +109,7 @@ public function getAuth() : AbstractAuth
      *
      * @return self The current Client instance.
      */
-    public function setAuth(AbstractAuth $auth) : self
+    public function setAuth(AbstractAuth $auth): self
     {
         $this->auth = $auth;
 
@@ -121,7 +121,7 @@ public function setAuth(AbstractAuth $auth) : self
      *
      * @return string The API URL to connect to.
      */
-    public function getApiUrl() : string
+    public function getApiUrl(): string
     {
         return $this->apiUrl;
     }
@@ -133,7 +133,7 @@ public function getApiUrl() : string
      *
      * @return self The current Client instance.
      */
-    public function setApiUrl(string $apiUrl) : self
+    public function setApiUrl(string $apiUrl): self
     {
         if (substr($apiUrl, -1) !== '/') {
             $apiUrl .= '/';
@@ -149,7 +149,7 @@ public function setApiUrl(string $apiUrl) : self
      *
      * @return LoggerInterface The log instance.
      */
-    public function log() : LoggerInterface
+    public function log(): LoggerInterface
     {
         if ($this->logger === null) {
             // If there's no logger set, use the NullLogger.
@@ -166,7 +166,7 @@ public function log() : LoggerInterface
      *
      * @return self The current Client instance.
      */
-    public function setLogger(LoggerInterface $log) : self
+    public function setLogger(LoggerInterface $log): self
     {
         $this->logger = $log;