Matrix Choice Laravel Package

Technical Evaluation

Package: lara-zeus/matrix-choice — a Filament form-field plugin that renders a rows × columns matrix with one selection per row. Release under review: 5.0.1 (patch). Ecosystem signals: 27 stars, 0 dependents, single primary maintainer, MIT licensed.

Architecture fit — favourable for a bounded UI primitive. The package is a presentation-layer extension to a Filament form schema. It does not own the data model, require migrations, introduce services, register queues, or dictate persistence. It inherits the host application's Livewire state, validation pipeline, and theming. From a TPM's standpoint this is the best possible shape for a third-party dependency: low coupling in both directions means the cost to adopt is low and the cost to exit is low. For a UI pattern that is genuinely expensive to hand-roll (Likert scales, NPS/CSAT batteries, onboarding questionnaires, skills self-assessments, compliance checklists, priority matrices) and that carries near-zero competitive differentiation, "buy" is the correct default. Adoption converts a multi-week custom-UI workstream into days of configuration and returns engineering capacity to differentiating work.

Integration feasibility — high, conditional on the stack. The mechanics are a Composer require plus a field class inside a form schema. No infrastructure, no external services, no data migration, no asset publishing. The real effort is verification rather than construction: confirm php / laravel/framework / filament/filament constraints against our pins, then exercise the field end-to-end on a representative form (render → select → validate → persist → re-render a saved record). Budget a half-day to one day for the spike. That is the entire integration risk envelope, which makes this an unusually cheap decision to make with real evidence rather than estimation.

What actually changed in 5.0.1. One functional change: feat: allow hiding specific options (#42). Everything else is documentation restructuring (#40) and three Dependabot bumps to CI tooling. No removals, no deprecations, no migration steps, no config or asset republication. The CI housekeeping is a positive maintenance-hygiene signal with zero runtime impact.

Technical risk — low overall, three items on the register.

1. SemVer discipline (process risk). A user-facing feature shipped in a patch release. Strictly additive and therefore backwards-compatible, but it signals loose management of minor/patch boundaries. Mitigation is cheap and non-negotiable: pin the exact version, read diffs before bumping, never assume "patch = inert."
2. Option-hiding semantics (correctness risk). "Hiding" is ambiguous with direct data-integrity consequences. Is it DOM-only, or does it also remove the option from server-side validation? Can a tampered request submit a hidden option? What renders when a persisted record references an option that later becomes hidden? This must be answered before the feature touches any data-bearing field — and answered with a test, not a README read.
3. Maintainership (support risk, not architecture risk). One primary maintainer, small community, 27 stars and zero dependents — little prior art, few eyes on edge cases, effective bus factor of one. Acceptable for a form input; not acceptable for anything owning data or auth. Mitigation is the vendoring fallback, feasible given the small surface, and worth costing now so it is a known number rather than a scramble mid-quarter.

Key questions for the spike / maintainer.

• Exact php / laravel / filament constraints for ^5.0.1, and is our current Filament major supported?
• Does hiding an option enforce server-side rejection, or is it presentation-only? Is there an authoritative allow-list?
• How is a persisted value referencing a now-hidden option rendered — graceful degradation or exception?
• Is option state static at schema-build time or reactive to sibling fields (plan, role, prior answers)?
• Is option hiding covered by tests, and does CI run a version matrix?
• Is there a funded maintenance path, or is this explicitly best-effort?

Verdict. Adopt for near-term questionnaire/matrix roadmap items, provided we are on Filament. 5.0.1 does not warrant a migration project or risk escalation. It does warrant pinning exact versions, gating the option-hiding feature behind a verification step, and keeping the field definition thin.

Integration Approach

Stack fit. Hard prerequisite: a Filament-based admin or forms surface on Laravel + Livewire. If the target application is not on Filament, the package does not apply — there is no headless or Blade-only path, and no workaround worth building. Filament's major version is the primary compatibility fault line; confirm alignment before scheduling any dependent work.

Migration path. No migration for 5.0.0 → 5.0.1; it is a drop-in Composer update. Teams on 4.x should treat 4.x → 5.x as the genuine migration boundary and plan it as its own line item — this assessment's guidance applies to the 5.x line only.

Compatibility. Read composer.json constraints directly rather than inferring from the changelog, and validate against our pins with composer why-not. Pay specific attention to PHP 8.4 / Laravel 12 adoption and Filament peer constraints, since that is where breakage surfaces first. Treat any Filament major upgrade as a mandatory retest trigger for this field.

Sequencing.

1. Spike (½–1 day). Branch install of exact 5.0.1; add the matrix field to one non-critical form; exercise normal selection, persistence, re-render of a saved record, and the option-hiding path including a tampered submission attempting to post a hidden option.
2. Semantics decision gate. Determine whether the roadmap item actually needs option hiding. If not, we avoid that feature risk entirely and can sit on 5.0.0. If yes, document expected server-side behaviour and decide whether to layer our own allow-list validation rule on top.
3. Contract test. Land a small test asserting hidden options are rejected server-side. This is the highest-value engineering artifact this adoption should produce — it prevents a future patch from silently changing security-relevant behaviour.
4. Pin and roll out. Enable Dependabot/Renovate with a grouped, human-reviewed PR policy scoped to this package; roll the field into the target form(s).
5. Defer breadth. Multiple matrix fields, cascading/dependent matrices, and scored output wait until the semantics spike closes. Keep the matrix schema declarative in one field class or config so a swap or vendoring remains a contained change.

Scope discipline. Keep validation rules, allow-lists, scoring, and persistence in our code. The field must remain a thin declarative layer over our domain model, never the place where business rules accumulate — that discipline is what preserves the cheap-exit property that justified adoption in the first place.

Operational Impact

Maintenance. Near-zero steady-state effort. No migrations, no scheduled jobs, no runtime services, no workers, no storage. The update stream is small and recently dominated by chore and Dependabot traffic. Realistic ongoing cost is a periodic dependency-bump review plus a retest on Filament majors — hours per quarter, not days. Ownership should sit with the team that owns the Filament forms surface, not a platform team.

Support. Best-effort, single maintainer, no SLA, no LTS, no commercial backstop. That is an acceptable support profile for a form input and would be disqualifying for anything owning data or auth. The organization's real support plan is the vendoring fallback: the surface is small enough to fork and maintain in-house if upstream stalls. Cost that now — a rough estimate is enough — so the contingency is a known number.

Scaling. No scaling surface to speak of: rendering is client-side plus standard Livewire round-trips. Two things to watch as usage grows — (a) very large matrices (many rows × many columns) increase payload and Livewire state size per request, so cap row/column counts per form and paginate long questionnaires at the form level rather than the field level; (b) repeated matrix fields on one long form compound the same cost. Neither is a blocker; both are design guardrails to write into the form conventions.

Failure modes.

• Upstream abandonment. Highest-likelihood, lowest-severity. Contained by pinning, declarative schema, and a costed vendoring option.
• Silent behavioural change in a patch. Mitigated by exact pinning, diff review, and the hidden-option contract test.
• Filament major upgrade breakage. Most likely technical break. Mitigated by treating Filament majors as a mandatory retest trigger.
• Data-integrity gap via option hiding. The one failure mode with real business consequence — a tampered or stale submission persisting an option the form no longer offers. Mitigated by the server-side allow-list rule and a defined rendering behaviour for orphaned values.
• Frozen rendering of historical records. If an option set changes, previously saved answers may no longer map to a visible label. Decide early whether the persisted value stores a stable key and how historical records render; do not let this be discovered during reporting work.

Ramp-up. Low. A developer familiar with Filament form schemas is productive within an hour using the fluent configuration API. Enablement material is one internal snippet plus the team convention: the matrix schema is declarative and lives in one place; validation, allow-lists, and scoring live in our code. One developer takes the spike end-to-end; no specialized skills, no training program, no onboarding artifact beyond the contract test and that convention note.

Roadmap framing for stakeholders. We can deliver the questionnaire/matrix surface on the roadmap by adopting a small, actively maintained MIT component instead of commissioning custom UI — a multi-week build becomes days of configuration, and per-context option hiding (new in 5.0.1) matches the per-persona and "not applicable" behaviour in the spec. Risk is contained: no breaking changes, presentation-layer only so the data model is not locked in, exact version pinning, and a costed exit path. Recommendation: adopt for the current roadmap item, fund a one-day spike to validate against our form requirements, gate option hiding behind the semantics test, and keep the field definition thin so a swap is a contained change.