Pager Bundle Laravel Package

Technical Evaluation

Architecture fit — the headline is a framework mismatch. Despite being filed under a Laravel/PHP package request, gloomy/pager-bundle is a Symfony bundle. It assumes Symfony's bundle registration and DI container, a Request object from symfony/http-foundation, and Twig-friendly rendering. There is no shim to Laravel's service providers, Illuminate container, Blade, or Illuminate\Http\Request. From a TPM standpoint this reframes the decision entirely: the deliverable is not "add a dependency," it is "decide whether to mine a design from a foreign-framework artifact."

What is actually worth having. The bundle's real idea is a uniform filter/sort/paginate contract that resolves against two data sources — a plain PHP array and a Doctrine Entity/QueryBuilder. That duality is the transferable asset: the same filter definitions drive in-memory fixtures in unit tests and live database queries in production, which is a genuine testability and acceptance-criteria win. In a Laravel context only the Eloquent/Query Builder and Collection analogues matter; the Doctrine half and the Twig half do not transfer at all. Value estimate: roughly the criteria-construction logic, a few hundred lines, and — more importantly — a vocabulary for writing filter requirements.

Integration feasibility. Three paths, and the ranking is not close:

1. Adopt as-is via a bridge — reject. Pulling Symfony HttpFoundation, DI, and Twig into a Laravel app for one list-screen concern is a worse trade than building the feature.
2. Fork and extract the adapters — moderate effort, preserves design intent, but inherits unfamiliar Symfony-idiom code your team will read once and maintain forever.
3. Reimplement the contract against Eloquent — lowest long-term risk, and the only path that leaves you with code your team wrote and understands.

Default recommendation: (3), with (2) justified only if the array-source adapter is specifically the blocker (federated search, cached result sets, third-party API aggregation).

Technical risk. Dominated by non-code factors. Ten stars, zero dependents, and a ~0.54 composite score mean no observable production footprint — no downstream users finding bugs, no release cadence to depend on, bus factor of one. There is no stated disclosure process for a component whose whole job is turning user input into query criteria, which is the injection-adjacent surface. Compatibility is unverified: PHP and Symfony/Doctrine version constraints must be confirmed before any extraction is scoped, and a Symfony bundle of this vintage may not support current LTS lines.

Key questions to close before spending engineering time: What PHP/Symfony versions does the latest release support, and when was the last commit? Is there a test suite, and does it cover filter-name-to-column mapping? Is field mapping an allowlist or does raw user input reach the query builder? Is pager state held in Twig/session constructs (killing separability)? And critically — does spatie/laravel-query-builder plus native pagination already cover the requirement? If yes, this whole thread closes.

Integration Approach

Stack fit. Assume Laravel + Eloquent + MySQL/Postgres. The mapping is: package Array source → Illuminate\Support\Collection; package Entity/QueryBuilder source → Illuminate\Database\Eloquent\Builder. The second mapping does not exist in the package and must be written. Treat the bundle strictly as a backend contract and discard the view layer — the pager UI gets re-expressed in Blade, Livewire, or (preferably) as JSON state consumed by a frontend that owns presentation.

Migration path. This is an extraction, not a migration; nothing is being replaced. Sequence:

1. Spike (1–2 days). Clone, attempt the test suite, verify version support, and read the filter-criteria code for field validation. Output: go/no-go on extraction. Timebox hard.
2. Contract definition. Specify FilterSet, SortSet, Paginator, and a DataSource abstraction mirroring the array/query split. This is the durable artifact — it outlives whichever tool wins.
3. Adapter implementation. Build CollectionDataSource and EloquentDataSource. Port the array logic if the spike passed; otherwise write it. Target 200–400 lines.
4. Pilot. Route one read-heavy admin list endpoint through the new layer behind a feature flag.
5. Disposition. Vendor the fork internally with the MIT notice retained, or drop the dependency once adapters are self-hosted.

Compatibility. MIT imposes no obstacle; retain the copyright notice if code is ported. Pin any temporary dependency to an exact version — never a caret constraint against an unmaintained package. Watch transitive Symfony component constraints (symfony/http-foundation, symfony/console are shared territory with Laravel); version skew there is a real breakage class.

Sequencing and budget. This must not block a roadmap item — it is a nice-to-have abstraction with no deadline. Slot the spike behind committed work. Budget one engineer-week including tests; beyond two weeks you are rebuilding the package and should have written it yourself. Fallback if the spike fails: Spatie Query Builder plus native pagination, and close the question permanently.

Operational Impact

Maintenance. Regardless of path, your team owns the resulting code — upstream will not ship fixes. The fork-vs-rewrite difference is purely whether you inherit unfamiliar Symfony-idiom code. Ongoing burden is low in volume but nontrivial in comprehension, so assign a named owner at extraction time. Unowned forked code is technical debt with a two-year fuse, and a Laravel repo containing Symfony-derived filtering logic will confuse future maintainers unless the ADR explains it.

Support. None. No vendor, no SLA, no community. Internal documentation and an ADR are the entire support model, and they are not optional.

Scaling. Two distinct profiles. Query-side pagination is as fast as the underlying query — but watch the second full COUNT(*) per page request, which on large filtered tables often dominates latency; consider keyset pagination if the datagrid is deep-pageable. Array-side pagination does not scale: filtering, sorting, and slicing an in-memory dataset is O(n) per request with the full set resident. Acceptable for cached sets in the hundreds to low thousands; unacceptable as a path to a primary data source. Impose a hard cap and a documented threshold above which the endpoint must move server-side.

Failure modes to plan for. Deep-page degradation from offset pagination; filter parameters silently ignored if field mapping is loose (a correctness bug users report as "search doesn't work"); collection endpoints that pass review at low data volume and fall over at 10k rows; and quiet divergence between the ported filter semantics and the original, producing test fixtures that pass while production filtering differs.

Ramp-up. Low absolute cost, non-zero: expect one to two days for an engineer unfamiliar with Symfony bundle conventions to read the criteria code confidently, plus the same again to map it onto Eloquent idioms. Front-load that reading into the spike so the estimate is real rather than discovered mid-implementation.