diff --git a/src/Exception/InvalidPaginationArgumentException.php b/src/Exception/InvalidPaginationArgumentException.php index db588f135669ca7d3d8a072fabf928c89759b50d..474b84b9cce315874f7e0b8533a0a7f310b0d2ca 100644 --- a/src/Exception/InvalidPaginationArgumentException.php +++ b/src/Exception/InvalidPaginationArgumentException.php @@ -48,6 +48,7 @@ class InvalidPaginationArgumentException extends \InvalidArgumentException imple * @param string $parameterName The name of the invalid parameter. * @param mixed $value The provided value for the parameter. * @param string $description Short description of what the parameter represents. + * * @return self An exception containing the invalid parameter and a message describing the expected value. */ public static function forInvalidParameter( @@ -73,6 +74,7 @@ class InvalidPaginationArgumentException extends \InvalidArgumentException imple * @param int $offset The pagination offset that was provided. * @param int $limit The pagination limit value (expected to be zero in this check). * @param int $nowCount The current count of items already paginated. + * * @return self An exception instance containing the keys `offset`, `limit`, and `nowCount` in its parameters. */ public static function forInvalidZeroLimit(int $offset, int $limit, int $nowCount): self @@ -99,6 +101,7 @@ class InvalidPaginationArgumentException extends \InvalidArgumentException imple * Retrieve the value for a named parameter stored on the exception. * * @param string $name Name of the parameter to retrieve. + * * @return mixed The parameter's value if set, or null if not present. */ public function getParameter(string $name): mixed @@ -117,4 +120,4 @@ class InvalidPaginationArgumentException extends \InvalidArgumentException imple { return $this->parameters; } -} \ No newline at end of file +} diff --git a/src/Exception/InvalidPaginationResultException.php b/src/Exception/InvalidPaginationResultException.php index db171b9f40affaae668e0e6728058f7a4f592b50..8670ae1dac5f54fa73e29e4eb294faece93d57ae 100644 --- a/src/Exception/InvalidPaginationResultException.php +++ b/src/Exception/InvalidPaginationResultException.php @@ -64,4 +64,4 @@ class InvalidPaginationResultException extends \UnexpectedValueException impleme ), ); } -} \ No newline at end of file +} diff --git a/src/OffsetAdapter.php b/src/OffsetAdapter.php index f733f0d1ae9832537584aa5f3c8b19a89b532c96..9284654ad5437b3a9e64546c35098dd0115ea038 100644 --- a/src/OffsetAdapter.php +++ b/src/OffsetAdapter.php @@ -44,6 +44,7 @@ readonly class OffsetAdapter * The callback is called with ($page, $pageSize) and must return a Generator yielding items of type `T`. * * @param callable(int, int): \Generator $callback Callback that provides page data. + * * @return self An adapter instance that uses the provided callback as its data source. */ public static function fromCallback(callable $callback): self @@ -59,7 +60,7 @@ readonly class OffsetAdapter * @param int $nowCount Current count of items already fetched (used for progress tracking across requests). * * @throws InvalidPaginationArgumentException If any argument is invalid (negative values or zero limit with non-zero offset/nowCount). - * @throws \Throwable For errors raised by the underlying source during data retrieval. + * @throws \Throwable For errors raised by the underlying source during data retrieval. * * @return OffsetResult A wrapper exposing the paginated items (via generator() and fetchAll()) respecting the provided offset and limit. */ @@ -80,8 +81,8 @@ readonly class OffsetAdapter /** * Return a generator that yields paginated results for the given offset and limit. * - * @param int $offset The zero-based offset of the first item to return. - * @param int $limit The maximum number of items to return; use 0 for no limit. + * @param int $offset The zero-based offset of the first item to return. + * @param int $limit The maximum number of items to return; use 0 for no limit. * @param int $nowCount The number of items already delivered prior to this call (affects internal page calculation). * * @throws \Throwable Propagates errors thrown by the underlying source. @@ -96,8 +97,8 @@ readonly class OffsetAdapter /** * Fetches all items for the given offset and limit and returns them as an array. * - * @param int $offset The zero-based offset at which to start retrieving items. - * @param int $limit The maximum number of items to retrieve (0 means no limit). + * @param int $offset The zero-based offset at which to start retrieving items. + * @param int $limit The maximum number of items to retrieve (0 means no limit). * @param int $nowCount The number of items already delivered before this call; affects pagination calculation. * * @return array The list of items retrieved for the requested offset and limit. @@ -113,10 +114,12 @@ readonly class OffsetAdapter * The returned generator yields generators (one per fetched page) that each produce items of type `T`. Pagination continues * until the overall requested `limit` is satisfied, the underlying source signals completion, or the computed page/page size is non-positive. * - * @param int $offset Number of items to skip before starting to collect results. - * @param int $limit Maximum number of items to return (0 means no limit). + * @param int $offset Number of items to skip before starting to collect results. + * @param int $limit Maximum number of items to return (0 means no limit). * @param int $nowCount Current count of already-delivered items to consider when computing subsequent pages. + * * @throws \Throwable Propagates unexpected errors from the underlying source or pagination logic. + * * @return \Generator<\Generator> A generator that yields per-page generators of items. */ protected function logic(int $offset, int $limit, int $nowCount): \Generator @@ -155,8 +158,8 @@ readonly class OffsetAdapter /** * Validate pagination arguments and throw when they are invalid. * - * @param int $offset Starting position in the dataset. - * @param int $limit Maximum number of items to return (0 means no limit). + * @param int $offset Starting position in the dataset. + * @param int $limit Maximum number of items to return (0 means no limit). * @param int $nowCount Number of items already fetched prior to this request. * * @throws InvalidPaginationArgumentException If any parameter is negative, or if `$limit` is 0 while `$offset` or `$nowCount` is non‑zero. @@ -183,10 +186,11 @@ readonly class OffsetAdapter /** * Yields items from the provided source generator while enforcing an overall limit. * - * @param \Generator $sourceGenerator Generator producing source items. - * @param int $limit Overall maximum number of items to yield; 0 means no limit. - * @param int &$totalDelivered Reference to a counter incremented for each yielded item. - * @param int &$currentNowCount Reference to the current "now" count incremented for each yielded item. + * @param \Generator $sourceGenerator Generator producing source items. + * @param int $limit Overall maximum number of items to yield; 0 means no limit. + * @param int &$totalDelivered Reference to a counter incremented for each yielded item. + * @param int &$currentNowCount Reference to the current "now" count incremented for each yielded item. + * * @return \Generator Yields items from `$sourceGenerator` until `$limit` is reached or the source is exhausted; updates `$totalDelivered` and `$currentNowCount`. */ private function createLimitedGenerator( @@ -207,14 +211,15 @@ readonly class OffsetAdapter } /** - * Decides whether pagination should continue based on the requested limit and items already delivered. - * - * @param int $limit The overall requested maximum number of items; zero indicates no limit. - * @param int $delivered The number of items delivered so far. - * @return bool `true` if pagination should continue (when `$limit` is zero or `$delivered` is less than `$limit`), `false` otherwise. - */ + * Decides whether pagination should continue based on the requested limit and items already delivered. + * + * @param int $limit The overall requested maximum number of items; zero indicates no limit. + * @param int $delivered The number of items delivered so far. + * + * @return bool `true` if pagination should continue (when `$limit` is zero or `$delivered` is less than `$limit`), `false` otherwise. + */ private function shouldContinuePagination(int $limit, int $delivered): bool { return 0 === $limit || $delivered < $limit; } -} \ No newline at end of file +} diff --git a/src/OffsetResult.php b/src/OffsetResult.php index 7fe222712728bb109300047f364e44afde5e0a8f..bc7077f291b51739b5ab5460abda84766d87324d 100644 --- a/src/OffsetResult.php +++ b/src/OffsetResult.php @@ -55,12 +55,12 @@ class OffsetResult } /** - * Retrieve the next item from the internal generator. - * - * The internal generator is advanced so subsequent calls return the following items. - * - * @return T|null The next yielded value, or `null` if there are no more items. - */ + * Retrieve the next item from the internal generator. + * + * The internal generator is advanced so subsequent calls return the following items. + * + * @return T|null The next yielded value, or `null` if there are no more items. + */ public function fetch(): mixed { if ($this->generator->valid()) { @@ -115,13 +115,14 @@ class OffsetResult } /** - * Flatten a generator of page generators and yield each item in sequence. - * - * Increments the instance's fetched count for every yielded item. - * - * @param \Generator<\Generator> $generator Generator that yields page generators; each page generator yields items of type T. - * @return \Generator Generator that yields items of type T from all pages in order. - */ + * Flatten a generator of page generators and yield each item in sequence. + * + * Increments the instance's fetched count for every yielded item. + * + * @param \Generator<\Generator> $generator Generator that yields page generators; each page generator yields items of type T. + * + * @return \Generator Generator that yields items of type T from all pages in order. + */ protected function execute(\Generator $generator): \Generator { foreach ($generator as $pageGenerator) { @@ -131,4 +132,4 @@ class OffsetResult } } } -} \ No newline at end of file +} diff --git a/src/SourceCallbackAdapter.php b/src/SourceCallbackAdapter.php index f87a08f35ce1fbe4f3c39cb38bec030a9ab1720d..f8d0d8e6e634885b3dcc6185fb2451e88edb8b26 100644 --- a/src/SourceCallbackAdapter.php +++ b/src/SourceCallbackAdapter.php @@ -44,6 +44,7 @@ class SourceCallbackAdapter implements SourceInterface * Calls the adapter's callback with the provided page and page size and returns the resulting Generator. * * @throws InvalidPaginationResultException If the callback does not return a `\Generator`. + * * @return \Generator A Generator that yields page results of type `T`. */ public function execute(int $page, int $pageSize): \Generator @@ -59,4 +60,4 @@ class SourceCallbackAdapter implements SourceInterface return $result; } -} \ No newline at end of file +} diff --git a/tests/ArraySource.php b/tests/ArraySource.php index 51c4d65bc38c4152fafe998a279b16e155533798..a0839d3638e1c6584177eca2f4e42a4eaff1bb82 100644 --- a/tests/ArraySource.php +++ b/tests/ArraySource.php @@ -30,12 +30,13 @@ class ArraySource implements SourceInterface } /** - * Provides the items for a specific page from the internal array. - * - * @param int $page Page number; values less than 1 are treated as 1. - * @param int $pageSize Number of items per page; if less than or equal to 0 no items are yielded. - * @return \Generator A generator that yields the items for the requested page. - */ + * Provides the items for a specific page from the internal array. + * + * @param int $page Page number; values less than 1 are treated as 1. + * @param int $pageSize Number of items per page; if less than or equal to 0 no items are yielded. + * + * @return \Generator A generator that yields the items for the requested page. + */ public function execute(int $page, int $pageSize): \Generator { $page = max(1, $page); @@ -44,4 +45,4 @@ class ArraySource implements SourceInterface yield from array_slice($this->data, ($page - 1) * $pageSize, $pageSize); } } -} \ No newline at end of file +}