Filament Auto Filters Laravel Package

Technical Evaluation

Architecture fit. Version 1.4.1 is an additive enhancement to the existing distinctOptionsUsing hook, which is the package's supported extension point for generating distinct-value option lists (typically for filter/select controls). It does not alter the service provider, config surface, or query layer. The change lets the callback return either a flat list (legacy) or an associative value => label map, which is the idiomatic Laravel pattern for decoupling stored values from display labels. This fits cleanly into existing Laravel conventions (callbacks returning arrays, config-driven thresholds) and requires no new dependencies.

Integration feasibility. High. The feature is opt-in: teams returning a flat list see identical behavior (natural sort, value-as-label). Adoption is a single callback change, not a structural refactor. The most valuable capability is server-side label formatting (e.g., currency amounts, enum humanization) without duplicating mapping logic in Blade/Livewire/Inertia components.

Technical risk. Low overall, with a few contained edge cases:

• Serialization shape change. A flat list serializes to a JSON array; an associative map serializes to a JSON object. Any front-end component that assumes an array of scalars will need to handle both shapes. This is the primary integration hazard.
• PHP key coercion. Numeric-string keys become integers in PHP arrays; if values are numeric identifiers, key type consistency should be verified downstream.
• "Blank" semantics. The release states blank values are dropped but does not define blank (null, empty string, whitespace, 0, "0"). 0 is a legitimate option value (e.g., "zero amount") and dropping it would be a subtle data bug.
• Threshold interaction. distinct_max_options still applies; it is unclear whether the threshold counts before or after blank removal and whether it is evaluated on the map or the underlying distinct set.

Key questions.

1. What exactly qualifies as "blank," and is 0/"0" preserved?
2. Is distinct_max_options evaluated pre- or post-blank-filtering, and does ordering affect truncation?
3. How are duplicate labels or duplicate values in the returned map handled?
4. Does the callback run once per request, or once per distinct query (N+1 exposure when labels require lookups)?
5. Are labels escaped/translated by the package, or is that the caller's responsibility?
6. Is the flat-list vs. map distinction detectable by consumers, or does the package normalize output?

Integration Approach

Stack fit. Compatible with standard Laravel/PHP stacks and front-end layers that consume plain arrays (Blade, Livewire, Inertia, API resources). Because the package returns data rather than rendering UI, it remains front-end agnostic.

Migration path. No migration, schema change, or config change required. Existing flat-list implementations continue unchanged. Teams can adopt the map form incrementally, one filter at a time, by modifying only the distinctOptionsUsing callback for that field.

Compatibility. Backward compatible by construction (explicitly documented that flat lists retain prior behavior). The compatibility surface to validate is client-side: any component or test asserting an array shape must be updated to tolerate an object when the map form is used. Recommend auditing consumers of distinctOptionsUsing output before rollout, and confirming the package version constraint in composer.json is widened only after that audit.

Sequencing.

1. Pin/upgrade to 1.4.1 in a non-production branch; run the existing suite to confirm no regression on flat-list paths.
2. Pilot the map form on one low-traffic filter with a simple label transformation (e.g., status enum humanization).
3. Verify the serialized payload shape at the API/component boundary and update any array-assuming consumers.
4. Confirm threshold behavior against a high-cardinality field before enabling on large datasets.
5. Roll out to remaining filters; document the two return contracts in the team's internal conventions.

Operational Impact

Maintenance. Negligible ongoing cost — the change is additive and the callback contract is stable. The durable maintenance item is documentation: teams need a clear internal note on when to return a list versus a map, and on the blank-handling and ordering guarantees.

Support. Expect a modest support tail from two sources: (a) confusion when a filter suddenly renders as an object-shaped payload, and (b) label formatting questions (escaping, translation, number/currency formatting). Pre-empting both with a short internal guide should keep this near zero.

Scaling. The callback executes in the option-generation path, so cost scales with distinct cardinality, not row count — acceptable. The real scaling risk is indirect: if labels require lookups (e.g., joining a lookup table), a naive implementation can introduce N+1 queries at render time. Mitigate by resolving labels from a preloaded map or cache. The distinct_max_options threshold remains the primary guardrail against unbounded option payloads and should be tuned per field rather than left at a global default.

Failure modes.

• Front-end component breaks on object-vs-array payload (highest likelihood, low severity, caught in staging).
• Legitimate 0/"0" values silently dropped as "blank" (low likelihood, high severity — silent data loss in filters).
• Threshold truncation interacting with a custom order, producing confusing or unstable option sets on high-cardinality fields.
• Duplicate keys in the returned map causing silent overwrites by the callback author.
• Label lookups degrading page performance on wide filter panels.

Ramp-up. Low. A developer familiar with Laravel callbacks can adopt this in under an hour. The learning curve is almost entirely about the two output contracts and their serialization differences, not about the package itself. Net assessment: worth adopting for filters where display labels differ from stored values; low risk, small effort, and a genuine reduction in duplicated presentation logic.