Kit Paginator Bundle Laravel Package

Product Decisions This Supports

• Feature/roadmap: unblocking native-SQL listing screens. The underlying capability — paginating hand-written SQL (cross-schema joins, aggregate reports, legacy views) inside the same UI conventions as ORM-backed lists — is a real need for admin dashboards, reporting views, and migration-period screens. This package is a candidate answer to "how fast can we ship that one reporting screen without inventing pagination plumbing."

• Build vs. buy sizing. The realistic alternative is an in-house adapter of ~100–200 lines over Doctrine\DBAL (or, in Laravel, just DB::table(...)->paginate()). That alternative is small, testable, and owned. So "buy" only wins if the package is actively maintained and genuinely saves ongoing maintenance. At 1 star, 0 dependents, and a single publisher, the evidence does not support that — the decision defaults to build/borrow-the-pattern.

• Platform-fit gate — decide this first. Material mismatch: the package is a Symfony bundle wrapping KnpPaginatorBundle, not a Laravel package, despite the "Laravel/PHP package" framing. If the target app is Laravel, this is a non-decision: LengthAwarePaginator / cursorPaginate() over a raw query builder already solves it, with better ergonomics (JSON serialization, API resources, view helpers). If the target is Symfony + Knp already in the stack, the question becomes narrow and legitimate.

• Consistency investment. Keeping raw-SQL screens inside the same paginator/UI conventions as ORM screens is a genuine product-consistency win for a small team — fewer bespoke pagination widgets, one less thing to design and QA. That value is captured equally well by copying a small adapter in-house.

• Use cases where the value is real (if adopted): an internal admin listing over a legacy MySQL view; a cross-database report not expressible in DQL; a migration-period screen reading a raw SQL join while the domain model is refactored.

• Verdict surfaced for planning: do not take as a dependency; borrow the pattern in-house when a native-SQL listing appears. Low cost, low risk either way — it does not move the roadmap.

When to Consider This Package

Consider it only when all of the following hold:

• The application is Symfony and already standardizes on KnpPaginatorBundle — the package is additive to an existing dependency, not a new paradigm.
• There is a genuine native-SQL listing that cannot reasonably be expressed in DQL/QueryBuilder, and the alternative is duplicating pagination logic in that screen.
• You have vetted the adapter code directly. With no community signal, due diligence is code-level: how it derives COUNT(*) for total pages (wrong counts on GROUP BY/DISTINCT are the classic failure), whether bindings are parameterized, and how LIMIT/OFFSET is handled per DB platform. Also confirm the supported matrix of PHP, Symfony, KnpPaginator, and Doctrine DBAL versions — with 0 dependents, upgrade lag is likely and yours to fix.
• You are willing to vendor or fork it on day one and own it, tests included, treating it as a code snippet rather than a consumed dependency.
• MIT license is acceptable (it is) and the code is small enough to audit in an afternoon (likely).

Look elsewhere — or build in-house — when:

• The stack is Laravel or any non-Symfony framework. Out of scope by construction; Laravel pagination is already native.
• You are not already on KnpPaginatorBundle. Introducing this means introducing Knp too; Pagerfanta with a DBAL adapter is the better-maintained single dependency for native-SQL pagination.
• The need is one screen. A ~150-line in-house adapter, fully tested, is cheaper over two years than an unmaintained bundle plus supply-chain and upgrade burden.
• You require security review, SLA, or vendor support — none exists here, and none is implied.
• Versions fall outside the package's composer constraints, or you need multi-database dialect support and deterministic ordering guarantees the package does not document.

Decision rule for the team: Symfony + Knp + more than a couple of native-SQL listings → copy the adapter into our codebase. Laravel, or Knp not already in the stack, or a single screen → build the small thing ourselves or use Pagerfanta.

How to Pitch It (Stakeholders)

For executives: We evaluated a small open-source component that extends an existing pagination library so that hand-written SQL queries — the kind behind internal reporting and admin screens where the ORM gets in the way — can be paginated with the same UI as the rest of the app. The idea is sound and the MIT license is permissive, but the project has essentially no adoption: one star, zero dependent projects, a single publisher. That means no community safety net, no support, and a strong likelihood we end up maintaining it ourselves — on a component that sits directly on the database boundary, where bugs show up as wrong numbers or slow pages in production rather than as build failures. Recommendation: don't take it as a dependency. Where we need the capability, we replicate the small adapter inside our own codebase — roughly a day of engineering — so we get the benefit with none of the supply-chain, security, or upgrade risk. If we're on Laravel, this is a non-issue: the framework already paginates raw queries natively. Low-cost, low-risk call; no roadmap impact.

For engineering (the ask): Don't add kitlabs/kit-paginator-bundle to composer. If we hit a native-SQL listing on the Symfony side, implement our own Knp paginator adapter over Doctrine\DBAL — we then control COUNT(*) semantics for GROUP BY/DISTINCT, parameter binding, deterministic ORDER BY, and the test suite. On Laravel, use LengthAwarePaginator / cursorPaginate() over the query builder. If we want an off-the-shelf answer on Symfony, Pagerfanta with a DBAL adapter is the better-supported option. If someone argues for the package anyway, the gate is: one-to-two-day spike against our pinned Symfony/Doctrine versions, verify count correctness and binding safety on a representative query, then vendor/fork behind a single call site.

Risk summary: MIT-licensed, small surface area, easy to audit — but unmaintained-looking, zero adoption, Symfony-only, and redundant with options we already control. Verdict: not adopted as a dependency; pattern borrowed in-house if and when needed.