Admin Listing Laravel Package

Technical Evaluation

Architecture fit. The package still augments Laravel/Eloquent listing/search behavior through ListingService, adding database-native accent-insensitive matching for MySQL/MariaDB and PostgreSQL. Release 2.2.0 does not change that architecture or the normalization strategy: it is a small API-surface and robustness release (a new OrderDirection enum, a configurable default order direction on ListingQueryBuilder::fromRequest(), and fixes for invalid orderDirection and null ListingQuery::$searchIn). For a TPM the value proposition is unchanged — multilingual search normalization without an external search service — but the package is now slightly more defensive about malformed request input, which matters for public-facing listing endpoints. It remains a poor fit where relevance ranking, faceting, or high-volume querying already require Elasticsearch/Meilisearch/OpenSearch.

Integration feasibility. 2.2.0 is a low-effort, additive upgrade for 2.x consumers. The new Brackets\AdminListing\Enums\OrderDirection enum and the optional $defaultOrderDirection parameter are backward compatible by signature (optional, defaulting to OrderDirection::Asc). The two fixes remove known failure modes: a non-string or invalid orderDirection now falls back instead of throwing, and a null searchIn no longer crashes ListingService. Both are behavior changes in edge cases rather than new capability, and neither touches the accent-insensitive query paths, collation requirements, or the PostgreSQL unaccent dependency flagged in the prior assessment. Internal changes (phpmd 3, CI coverage reporting, .gitattributes dist trimming) are hygiene improvements with no runtime impact.

Technical risk. The primary residual risk from 2.1.0 is unchanged: accent-insensitive matching broadens result sets and relies on non-sargable predicates (CONVERT(...), unaccent(), CAST(... AS TEXT)), with PostgreSQL behavior diverging between unaccent-enabled and fallback ILIKE environments. 2.2.0 introduces two new small semantic risks. First, ordering: callers that previously left orderDirection unset may now receive an explicit ascending order rather than whatever implicit/database-default ordering applied before — this can silently reorder listings and break snapshot tests or user expectations, so the prior effective ordering should be confirmed rather than assumed. Second, the null-searchIn fix means code paths that previously failed fast now return an unfiltered listing; if any endpoint relied on that exception as an implicit guard, it can now return more rows than intended. Neither risk is severe, but both are silent.

Key questions.

• Which Laravel, PHP, MySQL, MariaDB, and PostgreSQL versions are officially supported in the 2.2.x line?
• Is unaccent permitted in production PostgreSQL, and who owns extension lifecycle management?
• Does accent-insensitive search apply to all ListingService search paths, or only selected text columns?
• What is the documented opt-out for MySQL/MariaDB, comparable to dropping unaccent on PostgreSQL?
• Are there query plans or benchmarks showing index usage after CONVERT, unaccent, and CAST changes?
• What was the effective ordering before OrderDirection::Asc became the default, and do any consumer endpoints depend on it?
• Which code paths previously threw on a null searchIn, and are any of them externally reachable?
• What is the support policy for mixed PostgreSQL environments where some instances have unaccent and others do not?

Integration Approach

Stack fit. Unchanged. Best fit is a Laravel application using Eloquent/query-builder search over MySQL, MariaDB, or PostgreSQL, especially where users search accented text (names, addresses, product titles). If the product already uses an external search engine, this package is complementary for database-backed admin/listing screens, not a replacement for relevance-ranked search. The new OrderDirection enum is most useful where listing controllers accept sort direction from query strings and need a typed, validated default.

Migration path. Treat 2.2.0 as a drop-in minor upgrade but still validate ordering behavior. Bump the composer.json constraint (e.g. ^2.2), run the full suite against both MySQL/MariaDB and PostgreSQL, and add cases for: orderDirection omitted entirely, invalid/non-string values (e.g. orderDirection[]=asc, orderDirection=sideways), and a null searchIn configuration. Add response-shape or ordering assertions to listing endpoint tests, since the default direction may now pin an order that was previously implicit. Re-run the 2.1.0 accent and non-text-column cases to confirm no regression in the query layer.

Compatibility. Signature-compatible with 2.x; no schema migrations and no changes to the search predicates. Requirements remain utf8mb4 + target collation on MySQL/MariaDB, and the unaccent extension for full behavior on PostgreSQL (fallback to ILIKE without it). Note that CI now targets MariaDB 12.3, widening the gap between the tested matrix and older production versions — verify production MariaDB/MySQL versions explicitly rather than inferring support. The trimmed dist archive means local vendor copies no longer include dev/agent files; if any internal tooling read those, adjust it.

Sequencing.

1. Review the changelog and diff for the OrderDirection enum and fromRequest() signature; confirm default semantics against current behavior.
2. Bump the version and run the existing suite plus new ordering, invalid-orderDirection, and null-searchIn cases on all production database variants.
3. Diff listing endpoint responses (ordering and row counts) against 2.1.0 on production-like data.
4. Benchmark search latency and inspect query plans for the accent-insensitive predicates, as previously scheduled.
5. Validate PostgreSQL extension availability and fallback behavior in staging.
6. Update user-facing documentation and support runbooks for accent-insensitive results and default sort direction.
7. Roll out behind a feature flag or limited tenant scope; monitor search latency, error rates, and result-volume changes.
8. Document the opt-out path and database-specific behavior before broad release.

Operational Impact

Maintenance. Maintenance burden stays modest. The package is now more tolerant of bad input, which reduces defensive coding in consuming controllers. Operational complexity still comes from database-specific configuration — collation choice, PostgreSQL extension state, query shape — rather than from the application code. Coverage reporting in CI and the MariaDB 12.3 image improve signal, but operators must keep staging and production database configurations aligned, and must not treat the CI matrix as a support statement for older database versions.

Support. Support teams need clear guidance that accent-insensitive search is intentional and returns more results, and that listings now default to ascending order when no direction is supplied. The invalid-orderDirection fallback is a user-visible improvement (bad links no longer error), but support should know that a malformed sort parameter now silently resolves to the default rather than surfacing a failure — useful in tickets, potentially confusing if a user reports "sorting is ignored." PostgreSQL support must still distinguish unaccent-enabled from fallback environments; dropping unaccent to restore accent-sensitive behavior is a global database decision affecting other queries and should not be framed as a casual user-level toggle.

Scaling. Unchanged. Database-native normalization is convenient at low-to-moderate scale but may not scale on large tables if CONVERT, unaccent, or CAST prevent index use. For high-volume search, plan for functional indexes, generated columns, or an external search service. The null-searchIn fix can, in misconfigured deployments, turn a fast failure into a full-table listing query — worth watching in slow-query logs immediately after upgrade.

Failure modes. Likely failure modes include inconsistent results between PostgreSQL instances with and without unaccent; unexpected broadening of search results after upgrade; performance regressions from non-sargable predicates; version incompatibility with older MariaDB/MySQL deployments relative to the 12.3 CI target; residual type errors on column types not covered by the 2.1.0 CAST handling; silently changed listing order where orderDirection was previously omitted; and unfiltered listings returned from any code path that previously depended on a null-searchIn exception. The 2.2.0 fixes close two known error classes but convert them into quieter behaviors that are harder to detect without explicit tests.

Ramp-up. Low for Laravel developers familiar with Eloquent and query performance; the enum is self-explanatory. Moderate for database administrators due to collation, extension, and index-plan implications. A TPM should schedule a short database review, require staging validation on production-like data including ordering snapshots, and ensure documentation covers accent-insensitive behavior, default sort direction, PostgreSQL fallback behavior, and the operational cost of opting out.