Listable Laravel Package

Technical Evaluation

Architecture fit. staccato/listable positions itself as a repository abstraction that normalizes “list, paginate, filter, sort” across heterogeneous data sources — Eloquent models, arrays, external APIs, search indexes. Architecturally this is a familiar and legitimate pattern: a Listable contract plus an adapter per source, with a shared query-parameter parser and paginator bridge. For a TPM this is attractive because it promises one listing contract across the product surface, which reduces per-endpoint boilerplate and gives a single place to enforce pagination limits, allowed filters, and sort whitelists. The fit is strongest where a team already uses repository/service layers and has more than one backing store; it is weakest in a conventional Laravel CRUD app where Eloquent plus the built-in paginator already covers 90% of the need.

Integration feasibility. Composer-installable, MIT-licensed, Laravel-oriented. The real integration cost is not installation but the adapter work: each “listable source” needs a concrete implementation, and the package’s conventions (parameter naming, filter grammar, pagination metadata shape) must be mapped to your existing API contract. That is bounded, testable work — a spike of a few days, not a quarter. The absence of any documented dependents means you will be the first integrator for your stack combination; expect to read source rather than docs.

Technical risk. High, driven almost entirely by project health signals rather than code quality: 2 stars, 0 dependents, score 0.07. That implies no community validation, no downstream bug reports, no ecosystem pressure to keep it compatible with new Laravel releases, and a single-maintainer bus factor. Specific risks: (1) abandoned/unmaintained package with an unpinned Laravel constraint blocking framework upgrades; (2) filter/sort parameter handling that may not sanitize column names, creating SQL injection or mass-assignment exposure if fed untrusted query strings; (3) an abstraction whose escape hatches are thinner than advertised, forcing you to fork on first edge case; (4) no security disclosure process. None of these are disqualifying for a spike; all are disqualifying for an unpinned production dependency without a fork strategy.

Key questions. What Laravel/PHP versions are supported, and is the constraint range or pinned? Does the repo have CI and a meaningful test suite, and what is the last commit date? How are filter and sort keys validated — whitelist, schema introspection, or passthrough? Does it depend on illuminate/pagination and preserve the standard paginator contract (so Blade/Inertia/JSON resources keep working)? What is the license/CLA posture for forking? Who owns it internally if we adopt? What existing capability (Spatie Query Builder, Laravel’s paginate + when() clauses, API Resources) does this replace, and is the delta worth a dependency?

Integration Approach

Stack fit. Best fit: Laravel 9/10/11 services with a repository or action layer, multiple listing data sources (MySQL plus at least one of Elasticsearch, a third-party API, or cached arrays), and an API surface where clients send page, per_page, sort, and filter[...]. Poor fit: single-database CRUD apps, teams standardized on Spatie Query Builder or Laravel Scout, or any codebase that treats Eloquent as the domain layer rather than hiding it.

Migration path. Do not refactor existing endpoints. Introduce the package behind an internal interface — e.g. App\Contracts\ListingRepository — and implement that interface with listable in exactly one bounded context (an admin or internal listing screen with low blast radius). This gives you a reversible adoption: if the package stalls, you swap the implementation and keep the contract. Keep the package’s types out of controllers, resources, and domain code.

Compatibility. Pin the exact version in composer.json and record the supported Laravel/PHP matrix in your ADR. Verify the paginator output shape matches your existing JSON envelope before writing UI; mismatched meta/links keys are the most common integration tax. Check that it does not conflict with other packages decorating the query builder or the paginator resolver. Confirm PHP 8.2/8.3 compatibility explicitly rather than assuming.

Sequencing. (1) Timeboxed spike, 2–3 days: one Eloquent adapter, one non-Eloquent adapter, filter/sort/pagination round-trip, adversarial filter input. (2) Security and upgrade review of source. (3) Decision gate: adopt, adopt-with-fork, or extract the pattern in-house. (4) If adopt, vendor or fork under your org, add CI and a Laravel upgrade test, and document ownership. (5) Roll to one internal listing endpoint, then reassess before broadening.

Operational Impact

Maintenance. Treat this as internally owned from day one. With 2 stars and 0 dependents, there is effectively no upstream maintenance guarantee; you will be patching Laravel compatibility yourself. Budget a fork in your repository (or a Composer VCS/path repo) plus a smoke test that runs on every framework upgrade. That is a small but permanent carrying cost — realistic estimate: a few hours per Laravel major, plus occasional security triage.

Support. No vendor, no SLA, no community. Support means “whoever forked it.” Name that owner in the ADR and put the package on the same review cadence as your other third-party dependencies. Do not let it become load-bearing without that ownership being explicit.

Scaling. The abstraction adds indirection but negligible runtime overhead; performance is dominated by the underlying adapter. The scaling concern is behavioral: a generic filter/sort layer invites unbounded client-driven queries. Enforce per_page caps, filter and sort whitelists per endpoint, mandatory index coverage for sortable columns, and a hard timeout on external-source adapters. Without those, “filter anything, sort anything” becomes a database and support liability.

Failure modes. Most likely: silent behavior change after a Laravel upgrade (paginator contract drift); unvalidated filter keys reaching the query builder (injection or full-table scans); external adapter timeouts surfacing as 500s instead of degraded responses; the maintainer disappearing with no successor; and abstraction leakage forcing a fork at the worst moment — mid-sprint, with dependent endpoints already shipped. Mitigate by keeping the internal interface boundary, contract tests around the listing behavior, and a documented fallback to hand-written query scopes.

Ramp-up. Low for a mid-level Laravel engineer — the concepts are standard. The cost is documentation debt: with thin docs, onboarding requires reading the source and the internal adapter. Plan for one engineer to become the designated owner and write a short internal README covering the parameter grammar, whitelisting rules, and the fork/upgrade procedure. Given the project-health signals, the honest TPM recommendation is: use it as a design reference or a bounded spike, and only adopt in production if you are prepared to fork and own it — otherwise reproduce the pattern in-house in a day or two and keep the dependency count flat.