Json Rpc Paginator Bundle Laravel Package

Getting Started

• Install with composer require tourze/json-rpc-paginator-bundle. Before you commit, open the composer.json that lands in vendor/ and check the require block — despite the name, this is a Symfony bundle, not a Laravel package. Confirm whether the pagination logic lives in a framework-agnostic core (tourze/json-rpc-*) you can use directly, or whether it is welded to symfony/http-kernel / symfony/dependency-injection.
• Look first at: src/ (the paginator value object is the thing you actually care about), DependencyInjection/*Extension.php (tells you what services and config keys exist, which is the closest thing to documentation), tests/ (usually the most reliable usage reference in tourze packages), and README.md for the RPC method signature contract.
• The first use case to wire up: a single JSON-RPC method that returns a page of records. Pass page/perPage (or limit/offset) as params, run the query with a LIMIT/OFFSET and a separate COUNT, and return the paginator through whatever result envelope the bundle exposes so the client gets total, page, perPage, and items in a consistent shape.
• In Laravel terms, the mental model is LengthAwarePaginator, but the serialized payload is dictated by the bundle's contract, not by Laravel's toArray(). Do not assume they match.

Implementation Patterns

Wrap, don't replace, Eloquent. Keep your existing query builder / repository as the data source and construct the bundle's paginator from the already-sliced results plus an explicit total. This keeps the RPC layer thin and lets you swap the pagination implementation later without touching models.

$total = $query->count();
$items = $query->forPage($page, $perPage)->get();

return new Paginator($items->all(), $total, $page, $perPage);

Always apply a deterministic sort. Pagination without ORDER BY id (or another unique key) will silently duplicate and drop rows across pages once the table grows or rows are updated mid-scan. Do this even when the client doesn't ask for a sort.

Separate the envelope from the data. Return pagination metadata in a sibling key of items, never mixed into each record. If the bundle's normalizer does this for you, don't hand-roll arrays — you'll drift from the contract on the next upgrade.

Validate and cast params at the boundary. JSON-RPC params arrive as whatever the client sent; perPage is very often the string "20". Cast to int and clamp with max(1, min($perPage, 100)) before it reaches the query. Unbounded perPage is a trivial DoS vector and will also blow up the RPC response size.

Two pagination strategies. For admin/back-office endpoints, offset pagination with a COUNT is fine. For feeds, infinite scroll, or anything with a large or fast-moving table, prefer keyset/cursor pagination and set total to null rather than paying for COUNT(*) on every request. Decide per endpoint, not per project.

Bridge into Laravel deliberately. If there is no Laravel service provider, write one thin provider that binds the paginator factory into the container and registers any config. Do not let bundle-internal services leak into controllers — inject an adapter you own, so the Symfony coupling stays in one file.

Gotchas and Tips

• The 2.0.0 release notes contain only a changelog compare link — no prose, no migration guide. Treat this as a semver-major with unknown breakage. Before upgrading, actually read the diff: git diff 1.0.1..2.0.0 -- src/. The things to check specifically are the paginator constructor signature, service IDs / DI config keys, and the shape of the serialized payload. Any of those changing will break clients silently, since JSON-RPC consumers rarely validate the envelope.
• Pin to ^1.0.1 until you've read the diff. A major bump on a small, low-traffic package is often a PHP version floor raise or a namespace shuffle rather than a feature release — but you cannot know that from the release notes provided, and tourze/* packages have historically renamed classes between majors. Add a test that asserts the exact serialized pagination payload before and after the bump.
• Symfony-isms that will bite in Laravel: services.yaml config that Laravel won't load, attributes like #[AsController] or DI tags that are no-ops outside the Symfony kernel, and symfony/serializer normalizers that need explicit registration. If the package pulls in symfony/http-kernel, you're carrying a large unused dependency tree.
• COUNT(*) is the usual performance cliff. On InnoDB with a large table it's a full index scan. Cache the total with a short TTL for list endpoints, or drop total entirely for cursor-style pagination. Also watch for the count query and the data query drifting apart when joins or groupBy are involved — count() on a grouped query returns the wrong number.
• Page/perPage edge cases: page=0 or negative offsets produce SQL errors; perPage=0 returns an empty set that looks like a bug. Clamp both, and return a JSON-RPC invalid params error for out-of-range values instead of silently correcting them, so clients aren't surprised.
• Extension points: the adapter/normalizer seam (whatever the bundle calls it) is where you customise the envelope. If no interface exists for it, that's a signal the package isn't designed for reuse — in which case copy the paginator value object into your own codebase and drop the dependency. For 50 lines of total/page/perPage logic, an unmaintained third-party bundle is the expensive choice.
• Debugging: log the raw JSON-RPC request and response bodies at debug level in a middleware. Pagination bugs are almost always a param-casting or envelope-shape problem, and the RPC layer hides it from Laravel's exception handler.