Admin Listing Laravel Package

Product Decisions This Supports

• Search quality and localization: Accent-insensitive matching (since 2.1.0) means queries like Uložiť and Ulozit match each other. This directly supports multilingual/European user experiences and reduces failed searches caused by omitted diacritics.
• Default sort as a product policy, not a client concern: Release 2.2.0 adds ListingQueryBuilder::fromRequest(OrderDirection $defaultOrderDirection = OrderDirection::Asc) and a new Brackets\AdminListing\Enums\OrderDirection enum. PMs can now define the canonical ordering of a listing (e.g. newest-first for activity feeds, A–Z for catalogs) server-side, so a deep link or crawler request without ordering parameters renders the intended business ordering instead of an arbitrary default.
• Build vs. buy: The package encapsulates database-specific normalization for MySQL/MariaDB (CONVERT(... USING utf8mb4) COLLATE utf8mb4_unicode_ci) and PostgreSQL (unaccent() with ILIKE fallback). PMs can avoid custom, vendor-specific search SQL in application code.
• Roadmap sequencing: Teams can improve search relevance on the existing Laravel/database stack before investing in a dedicated search service such as Elasticsearch, Algolia, or Meilisearch.
• Broader searchable fields: PostgreSQL searches cast values to text, so searching numeric and date columns no longer raises type errors. This expands viable use cases to SKUs, prices, dates, IDs, and mixed-type listings.
• Request hardening (2.2.0): An invalid or non-string orderDirection in the request now falls back to the default instead of throwing, and ListingService no longer fails when searchIn is null. This reduces user-facing 500s from hand-edited URLs, bots, and cached/stale query strings — a small but real reliability and support-cost win that rarely gets prioritized as a feature.
• Release confidence: CI runs against PostgreSQL and MariaDB (now MariaDB 12.3), with added coverage reporting and coverage for attached and non-text column searches. Dev files are excluded from dist archives, so shipped artifacts stay lean.
• Product policy caveat: Accent-insensitive search is not always desirable for exact codes, legal names, or accent-sensitive content. PMs should define which fields use normalized matching versus exact matching.
• Performance decision point: MySQL/MariaDB collation changes and PostgreSQL CAST(... AS TEXT)/unaccent() can affect index usage and query performance. Validate on production-like listing volumes before broad rollout.

When to Consider This Package

• Consider it when a Laravel/PHP application needs simple listing search across MySQL/MariaDB/PostgreSQL, and users benefit from case- and accent-insensitive matching.
• Strong fit for multilingual catalogs, admin search, internal tools, and low-to-moderate complexity search where an external search service is overkill.
• Consider it when the team wants package-maintained database compatibility, request-parameter hardening, and test coverage instead of maintaining custom search SQL and ad-hoc sorting logic.
• Consider it when product needs a consistent, server-defined default ordering for listing pages that clients can override but not accidentally break.
• Check PostgreSQL unaccent availability: without the extension the package falls back to plain ILIKE, so accent-insensitive behavior will not apply. If accent-sensitive PostgreSQL search is required, dropping unaccent is a global database decision that may affect other application features.
• Look elsewhere for relevance ranking, stemming, synonyms, typo tolerance, faceting, high-scale search, or when exact/accent-sensitive matching must be the default. Also reassess if CAST(... AS TEXT) or collation changes create unacceptable performance or indexing constraints.

How to Pitch It (Stakeholders)

• Executives: Releases 2.1.0 and 2.2.0 improve search success for non-English users, fix database errors that blocked searching numeric/date fields, and make listing pages resilient to malformed sorting parameters. It is low-effort improvement on the existing Laravel stack, with no new search vendor required.
• Engineering: The package provides database-aware accent/case normalization, PostgreSQL unaccent() fallback, MariaDB collation handling, a typed OrderDirection default for fromRequest(), and graceful fallbacks for invalid orderDirection and null searchIn — backed by a PostgreSQL/MariaDB CI matrix with coverage reporting. It reduces custom SQL and defensive parsing code, but teams should review the PostgreSQL extension dependency and query performance implications.
• Product/operations: Treat this as an enabler for international search quality. Define per-listing default sort direction and decide which fields use accent-insensitive versus exact matching, then validate against production-like data and monitor zero-result and search-success rates before expanding usage.