Kit Paginator Bundle Laravel Package

Getting Started

First step: verify the stack, not the package. kitlabs/kit-paginator-bundle is a Symfony bundle that plugs into knplabs/knp-paginator-bundle so Knp can page over native SQL instead of DQL. It depends on Symfony's container/event system and Doctrine DBAL. In a Laravel app none of that exists, and Laravel already ships the capability the bundle advertises:

// Laravel — no package needed
$rows = DB::table('legacy_orders as o')
    ->join('customers as c', 'c.id', '=', 'o.customer_id')
    ->where('o.status', 'paid')
    ->orderBy('o.id')
    ->paginate(25);           // LengthAwarePaginator, Blade-ready

So "getting started" for a Laravel developer is: read the repo, confirm it's Symfony-only, and close the tab. The package is worth ~10 minutes of evaluation, not an afternoon.

If your team also runs Symfony services, the first use case is one internal listing backed by hand-written SQL — an admin report over a legacy view, a cross-schema join you can't express in DQL. The minimum viable setup:

composer require kitlabs/kit-paginator-bundle knplabs/knp-paginator-bundle
# config/bundles.php
// KitLabs\KitPaginatorBundle\KitPaginatorBundle::class => ['all' => true],

Then wrap one representative query and confirm three things before going further: the total count matches a manual COUNT(*), bindings are parameterized (not interpolated), and page 2 doesn't repeat rows from page 1. If any of those fail, stop — you're about to own the adapter anyway.

Where to look first in the repo: the adapter class implementing Knp's paginator interface. That file is the whole package. Everything else is Symfony glue.

Implementation Patterns

Pattern 1 — Symfony: native SQL through Knp's UI conventions. The point of the bundle is that a raw-SQL screen keeps the same knp_pagination_render() Twig call as your ORM screens. Consistency of UI across back-office listings is the only real win. Keep the raw query in a repository method and let the adapter own offset/limit.

Pattern 2 — supply your own count query. Don't let the adapter guess SELECT COUNT(*) FROM (<your query>). For anything with joins or aggregates, provide an explicit count query; it's usually 10–50× cheaper.

Pattern 3 — the Laravel translation of this pattern (what you'll actually do):

// Manual paginator over a raw result set
$page    = Paginator::resolveCurrentPage();
$perPage = 25;
$total   = DB::selectOne('SELECT COUNT(*) AS c FROM legacy_view WHERE status = ?', ['paid'])->c;
$rows    = DB::select(
    'SELECT * FROM legacy_view WHERE status = ? ORDER BY id LIMIT ? OFFSET ?',
    ['paid', $perPage, ($page - 1) * $perPage]
);
$paginator = new LengthAwarePaginator($rows, $total, $perPage, $page, [
    'path' => Paginator::resolveCurrentPath(),
]);

That is the entire capability. Bind your LIMIT/OFFSET as integers and pass the paginator into a Blade view with {{ $paginator->links() }}.

Pattern 4 — vendor, don't depend. If you do end up on the Symfony side with several native-SQL listings, copy the adapter into your own App\Pagination namespace, wire it as a service, and add tests. It's ~100–200 lines against Doctrine\DBAL\Connection. You keep the pattern, drop the supply chain.

Pattern 5 — cursor pagination for large tables. OFFSET degrades linearly. Laravel's cursorPaginate() over a raw query, or a hand-written keyset (WHERE id > ? ORDER BY id LIMIT ?), beats any offset-based adapter once the table gets big. This package gives you no hook for that.

Gotchas and Tips

The count query is where these things break. COUNT(*) wrapped around a query with GROUP BY or DISTINCT returns one row per group, not the total. If page counts are wrong, look there first — it's the classic failure mode and it fails silently.

Ordering must be deterministic. A native query with ORDER BY created_at and no unique tiebreaker will duplicate and skip rows across pages. Always append the primary key: ORDER BY created_at DESC, id DESC.

Check parameter binding by reading the source. A thin adapter that interpolates values into SQL is an injection vector sitting directly on your database boundary. This package has zero dependents and no security review — audit it yourself or don't use it.

Version pinning is your problem. The compatibility surface is the intersection of Knp's adapter interface, Doctrine DBAL's Connection API (changed materially in 3.x and again in 4.x), and your Symfony major. With no CI matrix upstream, pin exact versions and re-test on every bump.

It is effectively unmaintained. One star, zero dependents, single publisher, no release cadence. Budget an internal fork on day one, or skip it. Don't upstream fixes expecting a release.

Don't shim Symfony into Laravel. Bridging the container and event dispatcher to make a Knp adapter run under Laravel costs more than writing the twenty lines above, and you'd throw away LengthAwarePaginator's JSON-serialization and Blade ergonomics in the process.

Debugging tip: log the actual count query the adapter emits. Half the "pagination is wrong" bugs are an expensive or semantically wrong count, not the data query.

Extension point worth knowing: both Laravel's paginator and Knp's are view-agnostic — you can swap the renderer (Blade, Twig, JSON for an API) without touching the query layer. Keep pagination logic in the repository/service and rendering in the template, and you stay portable if you ever migrate.