diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 940b42a3..cb652ffb 100644 --- a/.github/CODEOWNERS +++ b/.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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 4ad6755a..008aabbf 100644 --- a/CHANGELOG.md +++ b/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 - - ## [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] diff --git a/bard.json b/bard.json index 7e6319fc..12e1ab61 100644 --- a/bard.json +++ b/bard.json @@ -102,6 +102,10 @@ "path": "src/SonsOfPHP/Contract/Money", "repository": "git@github.com:SonsOfPHP/money-contract.git" }, + { + "path": "src/SonsOfPHP/Contract/Pager", + "repository": "git@github.com:SonsOfPHP/pager-contract.git" + }, { "path": "src/SonsOfPHP/Contract/Version", "repository": "git@github.com:SonsOfPHP/version-contract.git" diff --git a/docs/contracts/pager/index.md b/docs/contracts/pager/index.md new file mode 100644 index 00000000..550b6de1 --- /dev/null +++ b/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 +``` diff --git a/mkdocs.yml b/mkdocs.yml index 4cb1d437..cda5b92a 100644 --- a/mkdocs.yml +++ b/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 diff --git a/src/SonsOfPHP/Contract/Pager/.gitattributes b/src/SonsOfPHP/Contract/Pager/.gitattributes new file mode 100644 index 00000000..3a01b372 --- /dev/null +++ b/src/SonsOfPHP/Contract/Pager/.gitattributes @@ -0,0 +1,2 @@ +/.gitattributes export-ignore +/.gitignore export-ignore diff --git a/src/SonsOfPHP/Contract/Pager/.gitignore b/src/SonsOfPHP/Contract/Pager/.gitignore new file mode 100644 index 00000000..d8a7996a --- /dev/null +++ b/src/SonsOfPHP/Contract/Pager/.gitignore @@ -0,0 +1,2 @@ +composer.lock +vendor/ diff --git a/src/SonsOfPHP/Contract/Pager/AdapterInterface.php b/src/SonsOfPHP/Contract/Pager/AdapterInterface.php new file mode 100644 index 00000000..518c8187 --- /dev/null +++ b/src/SonsOfPHP/Contract/Pager/AdapterInterface.php @@ -0,0 +1,34 @@ + + */ +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; +} diff --git a/src/SonsOfPHP/Contract/Pager/LICENSE b/src/SonsOfPHP/Contract/Pager/LICENSE new file mode 100644 index 00000000..39238382 --- /dev/null +++ b/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. diff --git a/src/SonsOfPHP/Contract/Pager/PagerExceptionInterface.php b/src/SonsOfPHP/Contract/Pager/PagerExceptionInterface.php new file mode 100644 index 00000000..255b915e --- /dev/null +++ b/src/SonsOfPHP/Contract/Pager/PagerExceptionInterface.php @@ -0,0 +1,12 @@ + + */ +interface PagerExceptionInterface {} diff --git a/src/SonsOfPHP/Contract/Pager/PagerInterface.php b/src/SonsOfPHP/Contract/Pager/PagerInterface.php new file mode 100644 index 00000000..3272a565 --- /dev/null +++ b/src/SonsOfPHP/Contract/Pager/PagerInterface.php @@ -0,0 +1,77 @@ + 2, 'max_per_page' => 10]); + * + * @author Joshua Estes + */ +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; +} diff --git a/src/SonsOfPHP/Contract/Pager/README.md b/src/SonsOfPHP/Contract/Pager/README.md new file mode 100644 index 00000000..f6615478 --- /dev/null +++ b/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 diff --git a/src/SonsOfPHP/Contract/Pager/composer.json b/src/SonsOfPHP/Contract/Pager/composer.json new file mode 100644 index 00000000..00a40359 --- /dev/null +++ b/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": "joshua@sonsofphp.com" + } + ], + "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" + } + ] +}