Utils.common.paginable Interface Laravel Package

Technical Evaluation

Architecture fit

• The package is a single PHP interface (composer name mouf/utils.common.paginable-interface, MIT, from the Mouf/TheCodingMachine ecosystem). It declares one method — paginate($limit, $offset) — and ships no implementation, no service provider, no config, no exception types. It is a naming contract, not a pagination library.
• It fits only one role: a domain-layer contract for "a data source that can return a slice." That is genuinely useful in a layered/hexagonal design where Eloquent repositories, external REST adapters, Elasticsearch adapters, and in-memory collections must be interchangeable behind one interface.
• It is not a fit for Laravel's pagination surface. Laravel's contract is Illuminate\Contracts\Pagination\LengthAwarePaginator (items + total + perPage + currentPage), hydrated by paginate() on the query builder and rendered by $paginator->links() / API Resources. This interface returns a bare slice with no total, no page number, no cursor, and no way to signal "there is more." Treating it as the HTTP pagination contract would break Blade pagination and the standard meta/links JSON shape.
• Net: acceptable as an internal repository abstraction, unsuitable as a presentation-layer contract.

Integration feasibility

• Composer install is trivial in principle; the practical risk is the 2017 release date. The composer.json platform constraint is likely ^7.0 or earlier, which Composer 2 will reject on PHP 8.1+. Expect to need a fork or --ignore-platform-reqs (the latter is not acceptable for production).
• Zero dependents and 1 star mean no third-party validation against Laravel 10/11 or PHP 8.2/8.3. There is no compatibility test matrix to rely on.
• No Laravel package discovery, so there is nothing to register; binding it into the container is a one-line Provider alias if you choose to.
• The abstraction surface is ~5–10 lines. Build-versus-adopt strongly favors building it in app/Contracts or an internal platform/contracts package, unless you are standardizing across multiple services that already speak this exact signature.

Technical risk

• Abandonment: last release 2017-05-17; no upstream maintenance. You inherit all future PHP compatibility work for a file you could have written in a minute.
• Semantic gap: offset/limit pagination is unstable under concurrent writes (duplicate and skipped rows) and provides no total, so UIs cannot render page counts, jump-to-last, or reliably detect end-of-data except via an empty or short page.
• Signal quality: 1 star, 0 dependents, package score 0.005. The 45.45 "opportunity" sub-score reflects an uncrowded niche, not demand. Do not treat it as adoption evidence.
• Supply chain: low security surface (no executable logic), but abandoned-package flags in composer audit/Dependabot will generate recurring noise in compliance reviews.
• Verdict: do not add this as a production dependency. Either define the contract in-house, or fork it under your org with PHP 8 support, a pinned tag, and MIT attribution retained.

Key questions

1. What is the exact FQCN and the documented return type of paginate() — array, iterable, or Collection? This determines every adapter's implementation.
2. What is the php constraint in composer.json, and does it install cleanly on PHP 8.2/8.3 under Composer 2?
3. Is there a companion total-count interface in the same family, and does any consumer actually use it?
4. Do our UIs require total counts or cursor stability? If yes, this contract is insufficient regardless of maintenance status.
5. Are we standardizing across multiple services that already implement this signature, or is this a single-app decision?

Integration Approach

Stack fit

• Laravel 10/11 on PHP 8.1+, Composer 2. This is not a Laravel package — no provider, facade, config, or migration. It slots in, if at all, as a plain PHP dependency in the domain layer.

Migration path

• Preferred: declare app\Contracts\Paginable (or App\Data\Contracts\Paginable) with paginate(int $limit, int $offset): iterable. Zero dependency, no fork, no abandoned-package flag, identical semantics.
• If cross-service standardization is the driver: fork to <org>/paginable-interface, add PHP 8.x support and a php: >=8.1 constraint, publish to a private registry (Satis / private Packagist), and pin an exact tag. Preserve the MIT license text.
• Do not consume the public abandoned tag directly.

Compatibility

• PHP: assume incompatible until proven; validate in a scratch app before committing.
• Laravel: no conflicts, no auto-discovery, no version coupling.
• PSR-4: verify autoload mapping and namespace casing; Mouf-era packages occasionally predate strict PSR-4 conventions.

Sequencing

1. Spike (0.5 day): install in a throwaway Laravel 11 container on PHP 8.3; capture the exact FQCN, signature, and platform constraint.
2. Decision gate: in-house contract vs. internal fork, based on whether more than one service already speaks the signature.
3. Adapters: Eloquent repository using ->offset($offset)->limit($limit); external HTTP client adapters; an in-memory implementation for unit tests.
4. Edge bridge: a transformer that wraps adapter output in LengthAwarePaginator (where a count is available) or CursorPaginator (for large, high-churn datasets) so controllers, Blade, and API Resources never see the internal contract.
5. Guardrail: an architecture test (e.g., Pest arch expectations) asserting the interface is not referenced from Http/, Resources/, or controllers.
6. Documentation: one paragraph stating this is an internal data-access contract, not the API pagination contract, plus the validation rules each implementation must enforce (non-negative offset, bounded limit).

Rollback: because the contract is a one-file abstraction, removal is a mechanical refactor across a small number of adapters — a strong argument for inlining it rather than depending on the package.

Operational Impact

Maintenance

• Effectively zero upstream maintenance. The interface is frozen, so there is no churn, but you own every future change: PHP 8.4/9 deprecation handling, Composer metadata, and any signature evolution. Inlining eliminates even that residual cost.
• Add to the dependency inventory with status "abandoned / internal fork" so security and license reviews do not re-litigate it each quarter.

Support

• No maintainers, no issue triage, no security policy. MIT grants full fork rights, so the exit path is always available and cheap. Ramp-up for any PHP developer is minutes — limit/offset is universally understood; the training cost is governance, not comprehension.

Scaling

• The interface adds no runtime overhead. The pagination strategy it encodes does: offset scans are O(offset), so deep pages on large tables degrade progressively. There is no cursor contract, so high-volume or fast-changing datasets will need a separate abstraction.
• Absence of totals means admin and reporting UIs cannot show page counts or totals without a second, out-of-contract count query — which reintroduces the coupling the interface was meant to remove.

Failure modes

• Install-time: Composer platform-constraint failure on PHP 8; workaround via --ignore-platform-reqs silently ships an untested combination.
• Correctness: duplicate or skipped rows across pages under concurrent writes — inherent to offset pagination, not a defect of this package.
• Semantic ambiguity: consumers cannot distinguish "last page exactly full" from "more data available" without an extra probe.
• Contract looseness: no validation of limit/offset, so each implementation must independently guard against negative offsets, unbounded limits, and out-of-range values.
• Type ambiguity: undocumented return type (array vs. iterable vs. Collection) produces adapter inconsistencies that surface as runtime errors downstream.
• Supply-chain noise: abandoned-package warnings recurring in every audit cycle.

Recommendation: Declare the contract in-house for a single Laravel application. Fork with a pinned tag and PHP 8 support only if multiple services already implement this exact signature. In all cases, keep LengthAwarePaginator/CursorPaginator at the HTTP boundary and confine this interface to the data-access layer.