Admin Listing Laravel Package

Technical Evaluation

Architecture fit. Unchanged by v3.5.0. brackets/admin-listing remains the query-building layer of the BRACKETS admin suite (admin-ui, admin-auth, admin-generator), not a standalone listing library. You define a Listing class, declare searchable/sortable columns and relations, and it returns a paginated, filtered, translated result set for an admin index table. Fit is binary: strong if we standardise on the Brackets admin panel, weak-to-poor as a general-purpose table/filtering layer for our own UI. It still contributes no UI, routes, or auth of its own, so evaluating it in isolation overstates value and understates coupling to the sibling packages.

Integration feasibility. Mechanically straightforward: Composer install, publish config, implement the Listing contract on a model-adjacent class, wire the route/controller (or let admin-generator scaffold it). Hours for a first screen, days to cover a real admin surface. v3.5.0 does not change this. The new page name attribute customisation is a small configuration affordance, not an architectural change — confirm it is opt-in and that the default request-param name is unchanged, because admin-ui's table component consumes that contract. The transitive commitment remains the real cost: to get the intended experience we pull admin-ui (Vue) and likely admin-auth, i.e. a UI stack and auth conventions.

Technical risk. Materially unchanged in kind, marginally improved in degree.

• Positive (small): v3.5.0 is the first release since 2023-10-30 and adds Laravel 10 support (PR #16) plus a configurable page-name attribute (PR #15). Two first-time contributors indicate the repo is not inert and that external patches are accepted. That is a genuine, if modest, improvement to the bus-factor signal.
• Still open: Laravel 10 is now an explicitly supported floor, but our targets are Laravel 11/12 and PHP 8.3+. The release narrows the compatibility gap without closing it. A query helper needing only illuminate/* usually keeps working; "usually" is still not a support statement.
• Adoption signal remains thin (low stars/dependents); the user base is the suite's user base.
• No published support or security policy; single-vendor stewardship with community patches is not the same as vendor-backed maintenance.
• Search across translatable/JSON columns implies raw SQL fragments; escaping and index behaviour still need confirmation before exposing it to arbitrary admin input.
• Minor: the page-name change modifies pagination parameter naming. Verify default behaviour is byte-identical for existing admin-ui consumers before upgrading.

Key questions. (Revised) With Laravel 10 now supported as of v3.5.0, is Laravel 11/12 on the roadmap, and on what timeline? Is the page-name attribute change backwards compatible by default, and does admin-ui depend on the old param name? Is v3.5.0 a one-off community burst or the start of sustained activity? What is the maintenance/bus factor posture — is the repo effectively archived? Does it function standalone or assume admin-ui request shapes (query param names, meta attachment contract)? What is the license, and are we permitted to fork and vendor? How does search handle column collisions, translatable fields, and relation-based sorting? What is the security-disclosure channel?

Integration Approach

Stack fit. Unchanged. Compelling only for a Laravel monolith on the Brackets admin stack, or one willing to adopt it. If our admin is Blade/Livewire/Filament/Inertia-based, the package fights us: its output contract targets admin-ui's table component. Confirm the frontend assumption before committing.

Migration path. Unchanged: do not retrofit. Introduce as a greenfield admin surface alongside the existing one — one or two low-risk CRUD listings with clean Eloquent models and no exotic joins. Keep the existing admin untouched until the POC proves both DX and framework compatibility. Abandonment stays a contained removal of a few Listing classes.

Compatibility. v3.5.0 gives us a defensible pin: if we are still on Laravel 10 anywhere, this release is the version to standardise on and it is now an explicitly supported target. If we are on 11/12, nothing here helps — the compatibility gate stands and we must test rather than assume. Pin the suite, verify PHP version in CI, freeze with a lockfile, and re-test search, sort, pagination and export on any framework upgrade. Add one item: verify the page-name attribute default against our admin-ui version before upgrading from 3.4.x.

Sequencing.

1. Spike: one listing screen, standalone (no admin-ui), to isolate what the package gives us versus the suite. Target v3.5.0.
2. Compatibility gate: CI matrix against our target Laravel/PHP — now including a Laravel 10 leg if that is in our estate, and an explicit L11/12 pass/fail. Check the issue tracker for breakage reports on the new release.
3. Upgrade check: diff 3.4.0 → 3.5.0 for the page-name default and any pagination param drift.
4. Decision gate: adopt whole suite, adopt listing only, or vendor a fork.
5. If adopting: standardise Listing class conventions, define export strategy (export hooks likely require an Excel dependency we own), document the meta-attachment contract.
6. Broader rollout only after step 5 survives a release cycle.

Operational Impact

Maintenance. Still low-churn and still effectively self-maintained, but the fork-within-12–18-months assumption can be softened slightly: v3.5.0 shows the project accepts outside PRs, so upstreaming a patch is a plausible path alongside forking. Neither is a support commitment. Keep a named owner and a fork-and-patch runbook. Survivable because the package is small and narrow; not survivable if the whole admin rests on an unmaintained parent suite.

Support. Community-only: GitHub issues, no SLA, no vendor escalation. v3.5.0 does not introduce a support policy or disclosure channel. Any production incident traces to our own on-call — an explicit accepted risk, not an implicit one.

Scaling. Unchanged; the package adds no server and cost scales with Eloquent. Watch LIKE '%term%' search on large tables, sorting on unindexed columns, relation-based filtering producing N+1s, client-controlled per-page values, and exports hitting memory/time limits. Mitigate with query budgets, capped perPage, indexes matched to declared sortable/searchable columns, and queued exports.

Failure modes. Silent framework breakage on upgrade; pagination contract drift from the new page-name attribute if defaults are misread; search behaving differently across translated/JSON columns; pagination inconsistencies when filters change mid-session; export jobs exhausting workers; and the organisational failure where the suite stalls unnoticed and the admin surface becomes a patching liability. Guards: CI compatibility matrix, golden-path integration tests on search/sort/paginate, a 3.4→3.5 upgrade diff, and a quarterly dependency review.

Ramp-up. Low — hours, not weeks, for any Laravel developer. The abstraction is thin and the mental model familiar. The genuine cost is learning the Brackets conventions (Listing contract, meta attachment, expected request params, and now the page-name attribute) plus the sibling packages, not this one. Document those conventions in-repo on day one.

TPM verdict. v3.5.0 is a modest, non-breaking improvement: Laravel 10 is now explicitly supported and the project demonstrates it accepts community patches. That is worth recording, not worth acting on alone — it does not close the Laravel 11/12 gap or supply a support commitment. Viable as a component of a deliberately scoped Brackets admin adoption, preferably pinned to v3.5.0; still not viable as a generally recommended dependency. Proceed only past the compatibility and decision gates, with a fork-ready posture and one named owner.