Pager Contract (#133)

## Description



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

.github/CODEOWNERS

@@ -1,7 +1,7 @@
 * @SonsOfPHP/Members
 
 # Make Documentation Team
-docs/ @SonsOfPHP/Members
+docs/ @JoshuaEstes
 
 # Each project needs a Team
 /src/SonsOfPHP/Bard @JoshuaEstes
@@ -20,4 +20,5 @@ docs/ @SonsOfPHP/Members
 /src/SonsOfPHP/**/Json @JoshuaEstes
 /src/SonsOfPHP/**/Logger @JoshuaEstes
 /src/SonsOfPHP/**/Money @JoshuaEstes
+/src/SonsOfPHP/**/Pager @JoshuaEstes
 /src/SonsOfPHP/**/Version @JoshuaEstes

CHANGELOG.md

@@ -8,19 +8,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 To get the diff for a specific change, go to https://github.com/SonsOfPHP/sonsofphp/commit/XXX where XXX is the change hash
 To get the diff between two versions, go to https://github.com/SonsOfPHP/sonsofphp/compare/v0.3.4...v0.3.5
 
-<!--
-Please Use (and keep them organized in this order as well):
- - Added for new features.
- - Changed for changes in existing functionality.
- - Deprecated for soon-to-be removed features.
- - Removed for now removed features.
- - Fixed for any bug fixes.
- - Security in case of vulnerabilities.
-
-Examples:
-* [PR #69](https://github.com/SonsOfPHP/sonsofphp/pull/69) Added new feature
--->
-
 ## [Unreleased]
 
 * [PR #51](https://github.com/SonsOfPHP/sonsofphp/pull/51) Added new Filesystem component
@@ -30,6 +17,7 @@ Examples:
 * [PR #112](https://github.com/SonsOfPHP/sonsofphp/pull/112) [Cache] Added new component
 * [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
 
 ## [0.3.8]
 

bard.json

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

docs/contracts/pager/index.md

@@ -0,0 +1,12 @@
+---
+title: Pager Contract
+---
+
+The PHP Pager Contract is to support libraries that implement Pagination related
+components.
+
+## Installation
+
+```shell
+composer require sonsofphp/pager-contract
+```

mkdocs.yml

@@ -117,3 +117,4 @@ nav:
         - contracts/index.md
         - Common: contracts/common/index.md
         - Cqrs: contracts/cqrs/index.md
+        - Pager: contracts/pager/index.md

src/SonsOfPHP/Contract/Pager/.gitattributes

@@ -0,0 +1,2 @@
+/.gitattributes export-ignore
+/.gitignore export-ignore

src/SonsOfPHP/Contract/Pager/.gitignore

@@ -0,0 +1,2 @@
+composer.lock
+vendor/

src/SonsOfPHP/Contract/Pager/AdapterInterface.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Contract\Pager;
+
+/**
+ * @author Joshua Estes <[email protected]>
+ */
+interface AdapterInterface extends \Countable
+{
+    /**
+     * This will return part of the total results
+     *
+     * Offset is where the results to be returned will start, for example, if
+     * offset is 0, it will start with the first record and return $length
+     *
+     * Offset should always be 0 or greater
+     *
+     * Length is how many results to return. For example, if length is 10, a
+     * MAXIMUM of 10 results will be returned
+     *
+     * Length should always be a positive number that is 1 or greater
+     *
+     * If null is passed in as length, this should return ALL the results.
+     *
+     * If the total number of results is less than length, an exception must
+     * not be thrown.
+     *
+     * @throws \InvalidArgumentException
+     *   If offset or length is invalid, this expection will be thrown
+     */
+    public function getSlice(int $offset, ?int $length): iterable;
+}

src/SonsOfPHP/Contract/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.

src/SonsOfPHP/Contract/Pager/PagerExceptionInterface.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Contract\Pager;
+
+/**
+ * Generic Pager Exception
+ *
+ * @author Joshua Estes <[email protected]>
+ */
+interface PagerExceptionInterface {}

src/SonsOfPHP/Contract/Pager/PagerInterface.php

@@ -0,0 +1,77 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Contract\Pager;
+
+/**
+ * The pager should take an adapter and optional arguments when being created.
+ *
+ * Example:
+ *   new Pager($adapter, ['current_page' => 2, 'max_per_page' => 10]);
+ *
+ * @author Joshua Estes <[email protected]>
+ */
+interface PagerInterface extends \Countable, \IteratorAggregate, \JsonSerializable
+{
+    /**
+     * This will return the current results based on the current page and max
+     * results per page
+     */
+    public function getCurrentPageResults(): iterable;
+
+    public function getTotalResults(): int;
+
+    public function getTotalPages(): int;
+
+    public function haveToPaginate(): bool;
+
+    public function hasPreviousPage(): bool;
+
+    /**
+     * If there is no previous page, this will return null
+     */
+    public function getPreviousPage(): ?int;
+
+    public function hasNextPage(): bool;
+
+    /**
+     * If there is no next page, this will return null
+     */
+    public function getNextPage(): ?int;
+
+    /**
+     * Returns the current page
+     *
+     * This should default to 1 if no current page is set.
+     */
+    public function getCurrentPage(): int;
+
+    /**
+     * The page must be 1 or greater
+     *
+     * If the page is out of bounds, this may throw an exception
+     *
+     * @throws \InvalidArgumentException
+     *   If $page is invalid
+     */
+    public function setCurrentPage(int $page): void;
+
+    /**
+     * This should return a default value if not set
+     *
+     * If max per page is set to null, this will return null
+     */
+    public function getMaxPerPage(): ?int;
+
+    /**
+     * The max per page should be a value of 1 or greater.
+     *
+     * If the value is set to null, and results are grabbed, all the results
+     * will be returned.
+     *
+     * @throws \InvalidArgumentException
+     *   If $maxPerPage is invalid
+     */
+    public function setMaxPerPage(?int $maxPerPage): void;
+}

src/SonsOfPHP/Contract/Pager/README.md

@@ -0,0 +1,16 @@
+Sons of PHP - Pager Contract
+============================
+
+## Learn More
+
+* [Documentation][docs]
+* [Contributing][contributing]
+* [Report Issues][issues] and [Submit Pull Requests][pull-requests] in the [Mother Repository][mother-repo]
+* Get Help & Support using [Discussions][discussions]
+
+[discussions]: https://github.com/orgs/SonsOfPHP/discussions
+[mother-repo]: https://github.com/SonsOfPHP/sonsofphp
+[contributing]: https://docs.sonsofphp.com/contributing/
+[docs]: https://docs.sonsofphp.com/contracts/pager/
+[issues]: https://github.com/SonsOfPHP/sonsofphp/issues?q=is%3Aopen+is%3Aissue+label%3APager
+[pull-requests]: https://github.com/SonsOfPHP/sonsofphp/pulls?q=is%3Aopen+is%3Apr+label%3APager

src/SonsOfPHP/Contract/Pager/composer.json

@@ -0,0 +1,52 @@
+{
+    "name": "sonsofphp/pager-contract",
+    "type": "library",
+    "description": "",
+    "keywords": [
+        "abstractions",
+        "contracts",
+        "decoupling",
+        "interfaces",
+        "interoperability",
+        "standards"
+    ],
+    "homepage": "https://github.com/SonsOfPHP/pager-contract",
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "Joshua Estes",
+            "email": "[email protected]"
+        }
+    ],
+    "support": {
+        "issues": "https://github.com/SonsOfPHP/sonsofphp/issues",
+        "forum": "https://github.com/orgs/SonsOfPHP/discussions",
+        "docs": "https://docs.sonsofphp.com"
+    },
+    "autoload": {
+        "psr-4": {
+            "SonsOfPHP\\Contract\\Pager\\": ""
+        }
+    },
+    "minimum-stability": "dev",
+    "prefer-stable": true,
+    "require": {
+        "php": ">=8.1"
+    },
+    "extra": {
+        "sort-packages": true,
+        "branch-alias": {
+            "dev-main": "0.3.x-dev"
+        }
+    },
+    "funding": [
+        {
+            "type": "github",
+            "url": "https://github.com/sponsors/JoshuaEstes"
+        },
+        {
+            "type": "tidelift",
+            "url": "https://tidelift.com/subscription/pkg/packagist-sonsofphp-sonsofphp"
+        }
+    ]
+}