Pager Component (#134)

## Description



## Checklist
- [x] Updated CHANGELOG files
- [x] Updated Documentation
- [x] Unit Tests Created
- [x] php-cs-fixer

.github/labeler.yml

@@ -46,17 +46,17 @@ JSON:
   - docs/components/json/*
   - src/SonsOfPHP/**/Json/*
 
-Money:
-  - docs/components/money/*
-  - src/SonsOfPHP/**/Money/*
-
 Logger:
   - docs/components/logger/*
   - src/SonsOfPHP/**/Logger/*
 
-Queue:
-  - docs/components/queue/*
-  - src/SonsOfPHP/**/Queue/*
+Money:
+  - docs/components/money/*
+  - src/SonsOfPHP/**/Money/*
+
+Pager:
+  - docs/components/pager/*
+  - src/SonsOfPHP/**/Pager/*
 
 Version:
   - docs/components/version/*

CHANGELOG.md

@@ -18,6 +18,7 @@ To get the diff between two versions, go to https://github.com/SonsOfPHP/sonsofp
 * [PR #119](https://github.com/SonsOfPHP/sonsofphp/pull/119) [HttpMessage] Added `withQueryParams` and `withQueryParam` to `Uri`
 * [PR #120](https://github.com/SonsOfPHP/sonsofphp/pull/120) [Logger] New Component
 * [PR #133](https://github.com/SonsOfPHP/sonsofphp/pull/133) [Pager] New Contract
+* [PR #134](https://github.com/SonsOfPHP/sonsofphp/pull/134) [Pager] New Component
 
 ## [0.3.8]
 

Makefile

@@ -58,6 +58,9 @@ test-cqrs: phpunit
 test-logger: PHPUNIT_TESTSUITE=logger
 test-logger: phpunit
 
+test-pager: PHPUNIT_TESTSUITE=pager
+test-pager: phpunit
+
 phpunit:
 	XDEBUG_MODE=$(XDEBUG_MODE) \
 	$(PHP) \
@@ -120,6 +123,9 @@ coverage-logger: coverage
 coverage-money:
 	XDEBUG_MODE=coverage $(PHP) -dxdebug.mode=coverage $(PHPUNIT) --testsuite money --coverage-html $(COVERAGE_DIR)
 
+coverage-pager: PHPUNIT_TESTSUITE=pager
+coverage-pager: coverage
+
 coverage-version:
 	XDEBUG_MODE=coverage $(PHP) -dxdebug.mode=coverage $(PHPUNIT) --testsuite version --coverage-html $(COVERAGE_DIR)
 

bard.json

@@ -70,6 +70,10 @@
             "path": "src/SonsOfPHP/Component/Money",
             "repository": "[email protected]:SonsOfPHP/money.git"
         },
+        {
+            "path": "src/SonsOfPHP/Component/Pager",
+            "repository": "[email protected]:SonsOfPHP/pager.git"
+        },
         {
             "path": "src/SonsOfPHP/Component/Version",
             "repository": "[email protected]:SonsOfPHP/version.git"

composer.json

@@ -45,7 +45,8 @@
         "sonsofphp/money-implementation": "0.3.x-dev",
         "sonsofphp/version-implementation": "0.3.x-dev",
         "psr/log-implementation": "^1.0 || ^2.0 || ^3.0",
-        "sonsofphp/logger-implementation": "0.3.x-dev"
+        "sonsofphp/logger-implementation": "0.3.x-dev",
+        "sonsofphp/pager-implementation": "0.3.x-dev"
     },
     "require": {
         "php": ">=8.1",
@@ -96,7 +97,9 @@
         "sonsofphp/version-contract": "self.version",
         "sonsofphp/common-contract": "self.version",
         "sonsofphp/logger": "self.version",
-        "sonsofphp/logger-contract": "self.version"
+        "sonsofphp/logger-contract": "self.version",
+        "sonsofphp/pager-contract": "self.version",
+        "sonsofphp/pager": "self.version"
     },
     "autoload": {
         "psr-4": {
@@ -117,6 +120,7 @@
             "SonsOfPHP\\Component\\Json\\": "src/SonsOfPHP/Component/Json",
             "SonsOfPHP\\Component\\Logger\\": "src/SonsOfPHP/Component/Logger",
             "SonsOfPHP\\Component\\Money\\": "src/SonsOfPHP/Component/Money",
+            "SonsOfPHP\\Component\\Pager\\": "src/SonsOfPHP/Component/Pager",
             "SonsOfPHP\\Component\\Version\\": "src/SonsOfPHP/Component/Version",
             "SonsOfPHP\\Contract\\Common\\": "src/SonsOfPHP/Contract/Common",
             "SonsOfPHP\\Contract\\Cqrs\\": "src/SonsOfPHP/Contract/Cqrs",
@@ -125,6 +129,7 @@
             "SonsOfPHP\\Contract\\Filesystem\\": "src/SonsOfPHP/Contract/Filesystem",
             "SonsOfPHP\\Contract\\Logger\\": "src/SonsOfPHP/Contract/Logger",
             "SonsOfPHP\\Contract\\Money\\": "src/SonsOfPHP/Contract/Money",
+            "SonsOfPHP\\Contract\\Pager\\": "src/SonsOfPHP/Contract/Pager",
             "SonsOfPHP\\Contract\\Version\\": "src/SonsOfPHP/Contract/Version"
         },
         "exclude-from-classmap": [
@@ -145,6 +150,7 @@
             "src/SonsOfPHP/Component/Json/Tests",
             "src/SonsOfPHP/Component/Logger/Tests",
             "src/SonsOfPHP/Component/Money/Tests",
+            "src/SonsOfPHP/Component/Pager/Tests",
             "src/SonsOfPHP/Component/Version/Tests"
         ]
     },

docs/components/pager/index.md

@@ -0,0 +1,79 @@
+---
+title: Pager
+description: PHP Pager
+---
+
+Simple yet powerful pagination
+
+## Installation
+
+```shell
+composer require sonsofphp/pager
+```
+
+## Usage
+
+Basic Usage
+
+```php
+<?php
+
+use SonsOfPHP\Component\Pager\Adapter\ArrayAdapter;
+use SonsOfPHP\Component\Pager\Pager;
+
+$pager = new Pager(new ArrayAdapter($results));
+
+foreach ($pager as $result) {
+    // ...
+}
+```
+
+Advance Usage
+
+```php
+<?php
+
+use SonsOfPHP\Component\Pager\Adapter\ArrayAdapter;
+use SonsOfPHP\Component\Pager\Pager;
+
+// These are the default option values
+$pager = new Pager(new ArrayAdapter($results), [
+    'current_page' => 1,
+    'max_per_page' => 10,
+]);
+
+// You can also set current page and max per page
+$pager->setCurrentPage(1);
+$pager->setMaxPerPage(10);
+```
+
+## Adapters
+
+### ArrayAdapter
+
+```php
+<?php
+
+use SonsOfPHP\Component\Pager\Adapter\ArrayAdapter;
+
+$adapter = new ArrayAdapter($results);
+```
+
+### CallableAdabter
+
+Will take any `callable` arguments.
+
+```php
+<?php
+
+use SonsOfPHP\Component\Pager\Adapter\CallableAdapter;
+
+$adapter = new CallableAdapter(
+    count: function (): int {
+        // ...
+    },
+    slice: function (int $offset, ?int $length): iterable {
+        // ...
+    },
+);
+```

phpunit.xml.dist

@@ -71,6 +71,10 @@
       <directory>src/SonsOfPHP/Component/Money/Tests</directory>
     </testsuite>
 
+    <testsuite name="pager">
+      <directory>src/SonsOfPHP/Component/Pager/Tests</directory>
+    </testsuite>
+
     <testsuite name="version">
       <directory>src/SonsOfPHP/Component/Version/Tests</directory>
     </testsuite>

src/SonsOfPHP/Component/Pager/.gitattributes

@@ -0,0 +1,4 @@
+/Tests export-ignore
+/phpunit.xml.dist export-ignore
+/.gitattributes export-ignore
+/.gitignore export-ignore

src/SonsOfPHP/Component/Pager/.gitignore

@@ -0,0 +1,3 @@
+composer.lock
+phpunit.xml
+vendor/

src/SonsOfPHP/Component/Pager/Adapter/ArrayAdapter.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Component\Pager\Adapter;
+
+use SonsOfPHP\Contract\Pager\AdapterInterface;
+
+/**
+ * @author Joshua Estes <[email protected]>
+ */
+class ArrayAdapter implements AdapterInterface
+{
+    public function __construct(
+        private array $array,
+    ) {}
+
+    public function count(): int
+    {
+        return count($this->array);
+    }
+
+    public function getSlice(int $offset, ?int $length): iterable
+    {
+        return array_slice($this->array, $offset, $length);
+    }
+}

src/SonsOfPHP/Component/Pager/Adapter/CallableAdapter.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Component\Pager\Adapter;
+
+use SonsOfPHP\Contract\Pager\AdapterInterface;
+
+/**
+ * @author Joshua Estes <[email protected]>
+ */
+class CallableAdapter implements AdapterInterface
+{
+    private $count;
+    private $slice;
+
+    public function __construct(callable $count, callable $slice)
+    {
+        $this->count = $count;
+        $this->slice = $slice;
+    }
+
+    public function count(): int
+    {
+        return call_user_func($this->count);
+    }
+
+    public function getSlice(int $offset, ?int $length): iterable
+    {
+        return call_user_func($this->slice, $offset, $length);
+    }
+}

src/SonsOfPHP/Component/Pager/LICENSE

@@ -0,0 +1,19 @@
+Copyright 2022 to Present Joshua Estes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.