Fix Pagination correctness and current Laravel parity

[binaryfire]

Summary

This PR fixes Pagination correctness issues across cursor decoding, query construction, page resolution, JSON serialization, database builders, relations, and Scout. It also brings the package up to date with current Laravel paginator behavior and type contracts while preserving Hypervel's coroutine-safe request ownership.

The changes keep paginator instances operation-local, retain boot-owned static configuration, and remove duplicate request resolution from the paginator hot path. Public Laravel APIs remain compatible except where an existing invalid input already failed deeper in the call stack or produced incorrect behavior.

For more details, see: docs/plans/2026-08-06-0928-pagination-correctness-current-parity-and-query-contracts.md

What changed

• Reject malformed cursor envelopes before strict construction while preserving valid mixed database order values.
• Preserve integer query keys and all supported paginator query values.
• Distinguish omitted pages from explicit zero and prevent invalid Scout pages from reaching search engines.
• Read request data directly from RequestContext without capturing request instances or resolving the request through the container.
• Keep lazy View factory resolution and Laravel-compatible contracts while making the local UrlWindow requirement explicit.
• Restore current Laravel behavior for zero-per-page length-aware pagination and indexed cursor result collections.
• Accept cursor objects through Eloquent relation pagination and restore concrete and generic paginator result types across Database builders.
• Make Pagination and related JSON boundaries throw JsonException without adding extra serialization passes.
• Restore current conditional and iterator types for Pagination, Routing, and Support surfaces.
• Make all paginator static reset state explicit and fully covered.
• Complete provider discovery, package metadata, user documentation, and the recorded Laravel differences.

Performance

The request resolvers now perform less work by reading coroutine request state once and avoiding container resolution. The only recurring added work is cursor result reindexing required by the public collection contract and a single integer clamp before Scout dispatch. No locks, retries, additional queries, network calls, unbounded caches, or retained request state are introduced.

Validation

• composer fix
• Focused Pagination, Database, Scout, Collections, Support, Sanctum, and API Client tests
• Database integration coverage for cursor pagination
• PHPStan type fixtures for paginator, builder, relation, Routing, and Support contracts
• Composer metadata and package discovery checks

Summary by CodeRabbit

• New Features

  • Improved pagination with more reliable cursor handling, query parameters, page validation, relationship support, and concurrent request behavior.
  • Pagination service is now automatically discovered during installation.
  • Pagination APIs provide clearer typing and broader support for query values.

• Bug Fixes

  • Explicit page zero values are handled consistently.
  • Invalid JSON data now raises clear encoding errors instead of failing silently.
  • Non-positive search result pages are clamped to page one.

• Documentation

  • Updated pagination documentation, package links, and Laravel compatibility details.

[coderabbitai]

📝 Walkthrough

Walkthrough

Pagination behavior, cursor validation, resolver lifecycle, JSON serialization, database contracts, Scout page handling, package metadata, and related tests were updated for current framework parity.

Changes

Pagination correctness and parity

Layer / File(s)	Summary
Pagination contracts and runtime behavior src/contracts/src/Pagination/*, src/pagination/src/*	Cursor inputs, query values, page handling, view factories, iterators, URL merging, JSON errors, and static-state reset behavior were updated.
Database and search pagination contracts src/database/src/..., src/scout/src/Builder.php, src/routing/src/Route.php, types/*	Database and relation pagination now expose corrected cursor and generic types. Explicit page values are preserved. Scout clamps pages to one or greater.
Throwing JSON serialization src/api-client/src/ApiResource.php, src/collections/src/*, src/sanctum/src/NewAccessToken.php, src/support/src/*	JSON conversion now uses JSON_THROW_ON_ERROR and documents JsonException.
Regression coverage and package wiring tests/Pagination/*, tests/Database/*, tests/Support/*, tests/Scout/*, composer.json, README.md, docs/plans/*	Tests cover the updated contracts and runtime behavior. Composer discovery, documentation, and audit records were updated.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant RequestContext
  participant PaginationState
  participant Paginator
  participant ViewFactory
  RequestContext->>PaginationState: provide page, query, path, and cursor values
  PaginationState->>Paginator: return request-scoped resolver results
  Paginator->>ViewFactory: resolve the view factory lazily
  ViewFactory-->>Paginator: return the configured view
  Paginator-->>Paginator: serialize output or render the paginator

Loading

Possibly related PRs

• hypervel/components#461: Both changes update cursor-parameter handling in AbstractCursorPaginator.
• hypervel/components#464: Both changes modify pagination behavior in src/scout/src/Builder.php.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 31.48% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the PR's main pagination correctness and Laravel parity changes.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch audit/pagination-correctness-parity

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR corrects pagination behavior and updates Laravel-compatible contracts while preserving coroutine-local request ownership.

• Rejects structured cursor parameters before they can be flattened into different query values.
• Corrects page resolution, query propagation, JSON errors, cursor collections, and zero-per-page behavior.
• Updates Database relation and builder pagination contracts, Scout page handling, package discovery, documentation, tests, and static-analysis fixtures.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the previously reported structured-cursor issue is prevented at every cursor construction path before query bindings are produced.

Important Files Changed

Filename	Overview
src/pagination/src/Cursor.php	Constructor-level validation now rejects array-valued cursor parameters across decoded, direct, and generated cursor paths, fully addressing the previous structured-value finding.
src/pagination/src/AbstractCursorPaginator.php	Updates cursor parameter and collection behavior while routing generated cursors through the new constructor invariant.
src/pagination/src/PaginationState.php	Resolves request pagination state directly from coroutine-owned request context without retaining request instances.
src/database/src/Concerns/BuildsQueries.php	Updates cursor and page resolution contracts used by Query and Eloquent builders.
src/scout/src/Builder.php	Clamps resolved pages before dispatching pagination requests to search engines.
tests/Pagination/CursorTest.php	Covers flat, nested, and empty structured cursor values for both encoded and direct construction paths.
tests/Integration/Database/EloquentCursorPaginateTest.php	Adds cursor-pagination integration coverage using isolated fixture models and hardcoded test data.

_{Reviews (2): Last reviewed commit: "Reject structured cursor parameters" | Re-trigger Greptile}

[binaryfire]

@greptile-apps Addressed the structured cursor finding in d21db9b.

The finding was valid. Cursor now rejects array-valued parameters at construction, before Query\Builder::flattenValue() can turn them into a different comparison value. This boundary covers decoded cursors, direct Cursor inputs, generated next/previous cursors, and user-created cursors. fromEncoded() keeps returning null for malformed public cursors, while direct and generated invalid cursors fail with the offending key.

The guard is intentionally limited to arrays. Backed enums and dates are valid bindings, and other unsupported objects already fail instead of changing value silently. Regression coverage includes flat, nested, and empty decoded arrays, direct construction, generated cursor links, and valid mixed values.

[binaryfire]

@greptile-apps Follow-up summary:

• Added one constructor-owned check that rejects array-valued cursor parameters before query construction.
• Preserved the existing null result for malformed encoded cursors and clear exceptions for direct or generated invalid cursors.
• Kept valid boolean, float, enum, date, and nullable cursor values unchanged.
• Added counterfactual coverage for every cursor entry path and updated the Pagination plan and audit record with the exact boundary and cost.

The complete composer fix gate is green. The change adds only a shallow scan of the small order-parameter map when a cursor is constructed; it adds no query, I/O, locking, or retained state.

[greptile-apps]

The fix is well-structured. The guard in the constructor is clear and correctly placed — catching arrays before flattenValue() can silently produce a different binding. A few observations:

The approach is sound. Rejecting at construction is the right boundary: it covers all four code paths (decoded, direct, generated, user-created) without duplicating the check in each callsite.

One minor consideration: The fromEncoded() path now constructs with a try/catch for InvalidArgumentException. That's correct, but worth confirming the null return is handled gracefully wherever the cursor is consumed in the paginator — specifically that a null cursor doesn't cause a silent "start from beginning" rather than a visible error when the cursor was valid JSON but contained array values (e.g., from a manually crafted URL). That's an existing behavior question rather than a new bug introduced here, but the change makes it more reachable.

The scope restriction to arrays only is appropriate. Backed enums serialize via BackedEnum::from() and dates are valid binding scalars downstream — excluding them from this guard is correct. The comment in the constructor makes the rationale explicit, which helps future readers.

Overall the fix looks correct and the test coverage (flat, nested, empty arrays + valid mixed values) is appropriately thorough. No issues with the implementation.

[greptile-apps]

The fix looks correct and well-scoped. A few observations:

What's solid:

• Guard at the value-object boundary is the right place — it fires before Query\Builder::flattenValue() ever sees the data, regardless of which entry point created the Cursor.
• fromEncoded absorbing InvalidArgumentException → null preserves the existing public contract cleanly.
• The pre-construction envelope validation (checking _pointsToNextItems exists and is bool) prevents a TypeError from reaching the constructor, which would have bypassed the InvalidArgumentException catch.
• Type widening on parameter() / parameters() to mixed is correct now that booleans, floats, and backed enums are valid values.

One minor inconsistency worth noting:

fromEncoded uses json_last_error() while encode() uses JSON_THROW_ON_ERROR. Both are functionally equivalent here since fromEncoded converts all errors to null anyway, but if you ever want to align styles, you could wrap json_decode with JSON_THROW_ON_ERROR in a catch (JsonException) returning null. Not a blocker — the current approach is correct.

Test coverage: testFromEncodedReturnsNullForStructuredParameters covering flat [5, 9], nested [['value' => 3]], and empty [] arrays, plus testConstructorRejectsArrayParameters for direct construction, is exactly the right surface to exercise. The backed enum and mixed-value tests confirm valid non-string types still pass through.

The finding is fully addressed. LGTM.

[greptile-apps]

The implementation looks correct. The changes are well-structured:

• The constructor guard catches array-valued parameters at the earliest point — before any query builder interaction.
• fromEncoded catches the InvalidArgumentException and degrades gracefully to null, preserving the existing contract for callers that already handle a nullable return.
• The envelope validation added before the new static(...) call (checking _pointsToNextItems exists and is bool) prevents a TypeError from ever reaching the constructor on malformed decoded input.
• Widening parameter() and parameters() return types to mixed is the correct fix for supporting legitimate non-string/int cursor values (floats, booleans, nulls, enums serialized as scalars).

One minor note: the @param array<array-key, mixed> docblock update is accurate since integer-keyed parameter arrays are now technically accepted by the type, though in practice only string keys are meaningful for cursor columns. If you want to be more precise you could use array<string, mixed>, but array-key is not incorrect and matches the broader PHP array contract — no action required if the current form is intentional.

Everything else looks clean. The shallow scan in the constructor loop is proportionate to the map size and adds no I/O or retained state as noted.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

tests/Scout/Unit/BuilderTest.php (1)

720-726: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use the callback's builder parameter or add a targeted suppression.

PHPMD reports $_ as unused at Line 721. Rename it to $builder and assert that the callback receives a Builder instance. If the parameter is intentionally positional, add a targeted PHPMD suppression instead.

Proposed cleanup

-            function (Builder $_, int $perPage, int $page) use (&$pages, $rawResults): array {
+            function (Builder $builder, int $perPage, int $page) use (&$pages, $rawResults): array {
+                $this->assertInstanceOf(Builder::class, $builder);
                 $this->assertSame(15, $perPage);

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/Scout/Unit/BuilderTest.php` around lines 720 - 726, Update the paginate
callback in the test to rename the unused Builder parameter from $_ to $builder
and assert that $builder is an instance of Builder, preserving the existing
pagination assertions and return behavior.

Source: Linters/SAST tools

tests/Integration/Database/EloquentCursorPaginateTest.php (1)

27-42: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Type each schema callback parameter.

Lines 27, 34, and 39 use untyped $table parameters. Use Blueprint $table, as line 19 already does.

As per coding guidelines, use native types for parameters wherever permitted.

Proposed fix

-Schema::create('test_users', function ($table) {
+Schema::create('test_users', function (Blueprint $table) {
@@
-Schema::create('test_owners', function ($table) {
+Schema::create('test_owners', function (Blueprint $table) {
@@
-Schema::create('test_post_user', function ($table) {
+Schema::create('test_post_user', function (Blueprint $table) {

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/Integration/Database/EloquentCursorPaginateTest.php` around lines 27 -
42, Update the schema callbacks in the test setup to type each $table parameter
as Blueprint, matching the existing typed callback nearby. Apply this to the
callbacks creating test_users, test_owners, and test_post_user, reusing the
file’s existing Blueprint import.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/pagination/README.md`:
- Line 8: Update the “Differences From Laravel” heading in the README to use
setext level-two Markdown syntax instead of ATX syntax, preserving the heading
text and level.

---

Nitpick comments:
In `@tests/Integration/Database/EloquentCursorPaginateTest.php`:
- Around line 27-42: Update the schema callbacks in the test setup to type each
$table parameter as Blueprint, matching the existing typed callback nearby.
Apply this to the callbacks creating test_users, test_owners, and
test_post_user, reusing the file’s existing Blueprint import.

In `@tests/Scout/Unit/BuilderTest.php`:
- Around line 720-726: Update the paginate callback in the test to rename the
unused Builder parameter from $_ to $builder and assert that $builder is an
instance of Builder, preserving the existing pagination assertions and return
behavior.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f65b56f3-5e0d-45d1-9d15-751a8e485d63

📥 Commits

Reviewing files that changed from the base of the PR and between af91108 and d21db9b.

📒 Files selected for processing (59)

• composer.json
• docs/plans/2026-07-12-0900-framework-coroutine-state-lifecycle-audit.md
• docs/plans/2026-07-12-0915-framework-coroutine-state-lifecycle-audit-ledger.md
• docs/plans/2026-08-06-0928-pagination-correctness-current-parity-and-query-contracts.md
• src/api-client/src/ApiResource.php
• src/boost/docs/pagination.md
• src/collections/src/Enumerable.php
• src/collections/src/Traits/EnumeratesValues.php
• src/contracts/src/Pagination/CursorPaginator.php
• src/contracts/src/Pagination/Paginator.php
• src/database/README.md
• src/database/src/Concerns/BuildsQueries.php
• src/database/src/Eloquent/Builder.php
• src/database/src/Eloquent/Relations/BelongsToMany.php
• src/database/src/Eloquent/Relations/HasOneOrManyThrough.php
• src/database/src/Query/Builder.php
• src/pagination/README.md
• src/pagination/src/AbstractCursorPaginator.php
• src/pagination/src/AbstractPaginator.php
• src/pagination/src/Cursor.php
• src/pagination/src/CursorPaginator.php
• src/pagination/src/LengthAwarePaginator.php
• src/pagination/src/PaginationState.php
• src/pagination/src/Paginator.php
• src/pagination/src/UrlWindow.php
• src/routing/src/Route.php
• src/sanctum/src/NewAccessToken.php
• src/scout/src/Builder.php
• src/support/src/Fluent.php
• src/support/src/Lottery.php
• src/support/src/MessageBag.php
• tests/ApiClient/ApiResourceTest.php
• tests/Database/DatabaseEloquentIntegrationTest.php
• tests/Database/DatabaseQueryBuilderTest.php
• tests/Integration/Database/EloquentCursorPaginateTest.php
• tests/Pagination/CursorPaginatorLoadMorphCountTest.php
• tests/Pagination/CursorPaginatorLoadMorphTest.php
• tests/Pagination/CursorPaginatorTest.php
• tests/Pagination/CursorResourceTest.php
• tests/Pagination/CursorTest.php
• tests/Pagination/LengthAwarePaginatorTest.php
• tests/Pagination/PackageMetadataTest.php
• tests/Pagination/PaginationResolverTest.php
• tests/Pagination/PaginatorLoadMorphCountTest.php
• tests/Pagination/PaginatorLoadMorphTest.php
• tests/Pagination/PaginatorResourceTest.php
• tests/Pagination/PaginatorTest.php
• tests/Pagination/UrlWindowTest.php
• tests/Sanctum/NewAccessTokenTest.php
• tests/Scout/Unit/BuilderTest.php
• tests/Support/SupportCollectionTest.php
• tests/Support/SupportFluentTest.php
• tests/Support/SupportMessageBagTest.php
• types/Database/Eloquent/Builder.php
• types/Database/Eloquent/Relations.php
• types/Database/Query/Builder.php
• types/Pagination/Paginator.php
• types/Routing/Route.php
• types/Support/Lottery.php

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Use the configured setext heading style.

Markdownlint reports MD003 for this heading. Replace the ATX heading with a setext level-two heading.

Proposed fix

-## Differences From Laravel
+Differences From Laravel
+-----------------------

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	## Differences From Laravel
	Differences From Laravel
	-----------------------

🧰 Tools

🪛 markdownlint-cli2 (0.23.2)

[warning] 8-8: Heading style
Expected: setext; Actual: atx

(MD003, heading-style)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/pagination/README.md` at line 8, Update the “Differences From Laravel”
heading in the README to use setext level-two Markdown syntax instead of ATX
syntax, preserving the heading text and level.

Source: Linters/SAST tools