Feature Pagination

README.md

@@ -12,6 +12,39 @@ DocuWare REST API. It is used to query the most common endpoints.
 [DocuWare REST API](https://developer.docuware.com/rest/index.html).
 See the documentation if you need further functionality. ⚠️
 
+## Table of Contents
+
+<!-- TOC -->
+  * [Table of Contents](#table-of-contents)
+  * [💡 What is DocuWare?](#-what-is-docuware)
+  * [🛠 Requirements](#-requirements)
+  * [SOmething else](#something-else)
+    * [> = v4.0 (alpha)](#---v40-alpha)
+    * [> = v3.0](#---v30)
+    * [> = v2.0](#---v20)
+    * [> = v1.2](#---v12)
+    * [< v1.2](#-v12)
+  * [⚙️ Installation](#-installation)
+  * [🏗 Usage](#-usage)
+  * [Pagination](#pagination)
+  * [🔍 Search usage](#-search-usage)
+  * [🖼 Make encrypted URL](#-make-encrypted-url)
+  * [🏋️ Document Index Fields DTO showcase](#-document-index-fields-dto-showcase)
+  * [🏋️ DTO showcase](#-dto-showcase)
+  * [🔐 Authentication](#-authentication)
+    * [Manual authentication](#manual-authentication)
+  * [📦 Caching requests](#-caching-requests)
+  * [💥 Exceptions explained](#-exceptions-explained)
+  * [✨ Events](#-events)
+  * [🔧 Configuration file](#-configuration-file)
+  * [🚧 Testing](#-testing)
+  * [📝 Changelog](#-changelog)
+  * [✏️ Contributing](#-contributing)
+  * [🧑‍💻 Security Vulnerabilities](#-security-vulnerabilities)
+  * [🙏 Credits](#-credits)
+  * [🎭 License](#-license)
+<!-- TOC -->
+
 ## 💡 What is DocuWare?
 
 DocuWare provides cloud document management and workflow automation software
@@ -243,6 +276,61 @@ $document = $connector->send(new PostDocumentRequest(
 $connector->send(new DeleteDocumentRequest($fileCabinetId, $document->id))->dto();
 ```
 
+## Pagination
+
+Requests that support pagination:
+
+| Requests                |
+|-------------------------|
+| GetDialogsRequest       |
+| GetDocumentsRequest     |
+| GetFieldsRequest        |
+| GetFileCabinetsRequest  |
+| GetOrganizationsRequest |
+| GetSearchRequest        |
+| GetSectionsRequest      |
+
+
+```php
+    $paginator = $connector->paginate(new GetDocumentsRequest(
+        config('laravel-docuware.tests.file_cabinet_id')
+    ));
+
+    // You can set the per page limit 
+    $paginator->setPerPageLimit(2);
+
+
+
+    // You can set the start page and how many pages you want to get
+
+     $paginator->setStartPage(3);
+     $paginator->setMaxPages(3); // Should be equal or more than the start page
+
+    // OR
+
+    $paginator->getSinglePage(3);
+
+
+
+    // Get the data from the paginator
+
+    $data = collect();
+
+    foreach ($paginator->collect() as $collection) {
+        $data->push($collection);
+    }
+
+    // OR
+
+    foreach ($paginator as $response) {
+        $data->push($response->dto());
+    }
+
+
+
+    $data->flatten()
+```
+
 ## 🔍 Search usage
 
 ```php
@@ -600,27 +688,6 @@ CodebarAg\DocuWare\DTO\TableRow {
 }
 ```
 
-```php
-CodebarAg\DocuWare\DTO\DocumentPaginator
-  +total: 39                                  // integer
-  +per_page: 10                               // integer
-  +current_page: 9                            // integer
-  +last_page: 15                              // integer
-  +from: 1                                    // integer
-  +to: 10                                     // integer
-  +documents: Illuminate\Support\Collection { // Collection|Document[]
-    #items: array:2 [
-      0 => CodebarAg\DocuWare\DTO\Document    // Document
-      1 => CodebarAg\DocuWare\DTO\Document    // Document
-    ]
-  }
-  +error: CodebarAg\DocuWare\DTO\ErrorBag {   // ErrorBag|null
-    +code: 422                                // int
-    +message: "'000' is not valid cabinet id" // string
-  }
-}
-```
-
 ## 🔐 Authentication
 
 You only need to provide correct credentials. Everything else is automatically

composer.json

@@ -29,8 +29,9 @@
     "illuminate/contracts": "^9.0|^10.0",
     "nesbot/carbon": "^2.64.0",
     "saloonphp/cache-plugin": "^3.0",
-    "saloonphp/saloon": "^3.0",
     "saloonphp/laravel-plugin": "^3.0",
+    "saloonphp/pagination-plugin": "^2.1",
+    "saloonphp/saloon": "^3.0",
     "spatie/laravel-package-tools": "^1.14.0"
   },
   "require-dev": {

src/Connectors/DocuWareDynamicConnector.php

@@ -6,8 +6,11 @@
 use CodebarAg\DocuWare\Support\Auth;
 use GuzzleHttp\Cookie\CookieJar;
 use Saloon\Http\Connector;
+use Saloon\Http\Request;
+use Saloon\PaginationPlugin\Contracts\HasPagination;
+use Saloon\PaginationPlugin\OffsetPaginator;
 
-class DocuWareDynamicConnector extends Connector
+class DocuWareDynamicConnector extends Connector implements HasPagination
 {
     public Config $configuration;
 
@@ -55,4 +58,9 @@ public function getConfiguration(): Config
     {
         return $this->configuration;
     }
+
+    public function paginate(Request $request): OffsetPaginator
+    {
+        return new DocuWareOffsetPaginator(connector: $this, request: $request);
+    }
 }

src/Connectors/DocuWareOffsetPaginator.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace CodebarAg\DocuWare\Connectors;
+
+use Illuminate\Support\Arr;
+use Saloon\Http\Request;
+use Saloon\Http\Response;
+use Saloon\PaginationPlugin\OffsetPaginator as SaloonOffsetPaginator;
+use Saloon\PaginationPlugin\Paginator;
+
+class DocuWareOffsetPaginator extends SaloonOffsetPaginator
+{
+    protected ?int $perPageLimit = 10000;
+
+    public function getSinglePage(int $page): Paginator
+    {
+        return $this->setStartPage($page)->setMaxPages($page);
+    }
+
+    protected function isLastPage(Response $response): bool
+    {
+        $count = Arr::get($response->json(), 'Count');
+
+        return $this->getOffset() >= (int) Arr::get($count, 'Value');
+    }
+
+    protected function getTotalPages(Response $response): int
+    {
+        $count = Arr::get($response->json(), 'Count');
+
+        return (int) ceil((Arr::get($count, 'Value') / $this->perPageLimit));
+    }
+
+    protected function getPageItems(Response $response, Request $request): array
+    {
+        return [
+            $response->dto(),
+        ];
+    }
+
+    protected function applyPagination(Request $request): Request
+    {
+        $request->query()->merge([
+            'count' => $this->perPageLimit,
+            'start' => $this->getOffset(),
+        ]);
+
+        return $request;
+    }
+}

src/Connectors/DocuWareStaticConnector.php

@@ -7,8 +7,11 @@
 use CodebarAg\DocuWare\Support\EnsureValidCredentials;
 use GuzzleHttp\Cookie\CookieJar;
 use Saloon\Http\Connector;
+use Saloon\Http\Request;
+use Saloon\PaginationPlugin\Contracts\HasPagination;
+use Saloon\PaginationPlugin\OffsetPaginator;
 
-class DocuWareStaticConnector extends Connector
+class DocuWareStaticConnector extends Connector implements HasPagination
 {
     public CookieJar $cookieJar;
 
@@ -47,4 +50,9 @@ public function getCoookieJar(): CookieJar
     {
         return $this->cookieJar;
     }
+
+    public function paginate(Request $request): OffsetPaginator
+    {
+        return new DocuWareOffsetPaginator(connector: $this, request: $request);
+    }
 }

src/DocuWareSearchRequestBuilder.php

@@ -17,10 +17,6 @@ class DocuWareSearchRequestBuilder
 
     protected array $additionalFileCabinetIds = [];
 
-    protected int $page = 1;
-
-    protected int $perPage = 50;
-
     protected ?string $searchTerm = null;
 
     protected string $orderField = 'DWSTOREDATETIME';
@@ -54,28 +50,6 @@ public function dialog(string $dialogId): self
         return $this;
     }
 
-    public function page(?int $page): self
-    {
-        if (is_null($page)) {
-            $this->page = 1;
-        } else {
-            $this->page = $page;
-        }
-
-        return $this;
-    }
-
-    public function perPage(?int $perPage): self
-    {
-        if (is_null($perPage)) {
-            $this->perPage = 50;
-        } else {
-            $this->perPage = $perPage;
-        }
-
-        return $this;
-    }
-
     public function fulltext(?string $searchTerm): self
     {
         $this->searchTerm = $searchTerm;
@@ -174,8 +148,6 @@ public function get(): GetSearchRequest
             fileCabinetId: $this->fileCabinetId,
             dialogId: $this->dialogId,
             additionalFileCabinetIds: $this->additionalFileCabinetIds,
-            page: $this->page,
-            perPage: $this->perPage,
             searchTerm: $this->searchTerm,
             orderField: $this->orderField,
             orderDirection: $this->orderDirection,
@@ -189,16 +161,6 @@ protected function guard(): void
             is_null($this->fileCabinetId),
             UnableToSearch::cabinetNotSet(),
         );
-
-        throw_if(
-            $this->page <= 0,
-            UnableToSearch::invalidPageNumber($this->page),
-        );
-
-        throw_if(
-            $this->perPage <= 0,
-            UnableToSearch::invalidPerPageNumber($this->perPage),
-        );
     }
 
     private function checkDateFilterRangeDivergence(): void

src/Requests/Dialogs/GetDialogsRequest.php

@@ -10,8 +10,9 @@
 use Saloon\Enums\Method;
 use Saloon\Http\Request;
 use Saloon\Http\Response;
+use Saloon\PaginationPlugin\Contracts\Paginatable;
 
-class GetDialogsRequest extends Request implements Cacheable
+class GetDialogsRequest extends Request implements Cacheable, Paginatable
 {
     use HasCaching;
 

src/Requests/Document/GetDocumentsRequest.php

@@ -11,8 +11,9 @@
 use Saloon\Enums\Method;
 use Saloon\Http\Request;
 use Saloon\Http\Response;
+use Saloon\PaginationPlugin\Contracts\Paginatable;
 
-class GetDocumentsRequest extends Request implements Cacheable
+class GetDocumentsRequest extends Request implements Cacheable, Paginatable
 {
     use HasCaching;
 

src/Requests/Fields/GetFieldsRequest.php

@@ -12,8 +12,9 @@
 use Saloon\Enums\Method;
 use Saloon\Http\Request;
 use Saloon\Http\Response;
+use Saloon\PaginationPlugin\Contracts\Paginatable;
 
-class GetFieldsRequest extends Request implements Cacheable
+class GetFieldsRequest extends Request implements Cacheable, Paginatable
 {
     use HasCaching;
 

src/Requests/FileCabinets/GetFileCabinetsRequest.php

@@ -12,8 +12,9 @@
 use Saloon\Enums\Method;
 use Saloon\Http\Request;
 use Saloon\Http\Response;
+use Saloon\PaginationPlugin\Contracts\Paginatable;
 
-class GetFileCabinetsRequest extends Request implements Cacheable
+class GetFileCabinetsRequest extends Request implements Cacheable, Paginatable
 {
     use HasCaching;
 

src/Requests/Organization/GetOrganizationsRequest.php

@@ -12,8 +12,9 @@
 use Saloon\Enums\Method;
 use Saloon\Http\Request;
 use Saloon\Http\Response;
+use Saloon\PaginationPlugin\Contracts\Paginatable;
 
-class GetOrganizationsRequest extends Request implements Cacheable
+class GetOrganizationsRequest extends Request implements Cacheable, Paginatable
 {
     use HasCaching;