Easy Pagination Laravel Package

Product Decisions This Supports

• API pagination contract standardization. Decides whether page / per_page parsing, defaults, and hard caps live in one shared helper or get re-implemented per endpoint. This package is a candidate reference implementation for that contract, not a platform commitment.
• Build vs. buy (narrow). Forces an explicit comparison between adopting a 2-star MIT utility and writing a ~40-line internal pagination value object. Given the adoption profile, "build" is a defensible and often preferable outcome; the package's main value is as a spec to copy from.
• Public/partner API roadmap. Useful input when defining pagination semantics ahead of partner integrations or SDK-facing endpoints, where predictable defaults and caps matter more than features.
• Multi-service consistency. Supports a decision to converge on a single pagination-input vocabulary across PHP/Laravel services and avoid per-team $request->get('page') drift.
• Scope boundary for "pagination." Clarifies that page/per-page input parsing is a separate concern from cursor pagination, sorting, filtering, and query execution — which shapes what you buy vs. build vs. defer.
• Dependency governance policy. A concrete test case for whether the org accepts single-vendor, zero-dependent, read-only-split packages as runtime dependencies. The answer here should generally be "only behind an adapter, pinned."
• Use cases in scope: REST/JSON list endpoints, internal service APIs, framework-agnostic request parsing, and CLI/queue contexts where Laravel's request-coupled paginate() doesn't fit.

When to Consider This Package

Consider it when:

• The team needs a small, generic helper to parse client pagination input and wants to stop duplicating defaults-and-caps logic across controllers.
• You are running a time-boxed spike (1–2 days) to standardize pagination semantics, and want a reference implementation to evaluate or copy.
• The codebase is genuinely framework-agnostic (or spans Lumen and plain PHP with PSR-7), so Laravel's native paginator is not available at the parsing layer.
• You can commit to wrapping it behind an internal interface (e.g., PaginationParamsFactory) so the vendor class never leaks into controllers, services, or repositories.
• You can pin an exact version and record the commit hash in the lockfile.

Look elsewhere when:

• Laravel's native paginator already covers the need. For Laravel-only services, paginate() plus form-request validation is fewer moving parts and has a maintainer.
• You need cursor pagination, complex sorting/filtering, query-builder integration, or high-scale public API behavior. This package does none of that.
• Security-sensitive enforcement is required. If per-page caps or input rejection must be guaranteed, verify the package actually clamps rather than merely transports — and enforce caps in your own adapter regardless.
• Long-lived, load-bearing infrastructure. Zero dependents, 2 stars, docs-only maturity, and a read-only subtree split mean your team becomes maintainer of last resort at the next PHP or Laravel major upgrade.
• The decision gate fails: if the source reveals a bare DTO with no validation and a dependency on illuminate/*, the case for adoption collapses to "copy the idea."

How to Pitch It (Stakeholders)

Executive summary. This is a tiny, MIT-licensed utility that parses client pagination parameters (page, per_page) with configurable defaults and upper limits, for Laravel/Lumen and plain PHP. It could cut repetitive code and improve API consistency, but it is not a strategic platform dependency: 2 stars, zero dependents, a read-only monorepo split, and docs-level maturity mean real lifecycle risk. Recommendation: approve a one-to-two-day evaluation or reference use only, isolated behind an internal adapter, pinned to an exact version, with a documented exit plan. A ~40-line in-house value object is a legitimate outcome of that evaluation and should not be treated as a failure.

Engineering summary. Understand the category first: this is a pagination-input library, not a paginator. It standardizes request parsing into a value object and sits underneath your existing query layer without competing with LengthAwarePaginator. Fit is clean in hexagonal/DDD codebases where pagination params are a domain concept; it is a poor fit where controllers already use Laravel's built-in pagination, because you'd run two parallel vocabularies.

Before adoption, verify in this order: composer.json PHP/Laravel constraints (below PHP 8.1 is a non-starter; check for illuminate/* coupling), src/ for actual validation behavior (does it cap per_page, reject negatives, handle missing params?), tests/ as the real edge-case spec, and tag dates in both the split and the parent monorepo. Then: wrap behind an interface, pilot on one low-traffic list endpoint for a sprint, and roll out only if it beats the in-house alternative ergonomically. Pin exactly; audit composer why for transitive eonx-com/easy-* creep. Runtime risk is negligible — constant per-request cost, no state, no scale concerns, almost no attack surface. The risk is upgrade maintenance: the package either keeps pace with PHP/Laravel or it doesn't, and with zero dependents nobody will notice first. Budget an annual review, triggered by every PHP minor bump, and enforce your own per-page caps in the adapter so a caller can never request 100,000 rows. Ramp-up for a mid-level developer is under an hour; the real cost is the governance convention that keeps the vendor class out of application code — track that during rollout, because it is what erodes first.