Laravel Searchable Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • Multi-column search: Supports direct columns, relations (BelongsTo/HasMany), morph relations, and cross-database relations in a single query, reducing the need for manual where clauses or complex joins.
  • Scout compatibility: Works alongside Laravel Scout, enabling hybrid search strategies (SQL for small datasets, dedicated search engines like Meilisearch for large-scale needs).
  • Filament integration: Seamless UI integration for admin panels, reducing frontend development effort.
  • Flexible query building: Supports dynamic column inclusion/exclusion (in, include, except) and external query limits for cross-database relations.
  • No config/migration overhead: Zero setup required beyond trait usage, lowering adoption friction.

• Limitations:

  • Performance constraints: Relies on LIKE '%term%', which is inefficient for large datasets (no index utilization). Requires Scout for scaling.
  • Case sensitivity: Database-dependent behavior (e.g., MySQL collation affects results) with no runtime override.
  • No full-text search: Limited to LIKE semantics; lacks advanced features like stemming, synonyms, or fuzzy matching.
  • Cross-database limitations: External relation queries are capped (default: 50 IDs) and use IN clauses, which can bloat queries.

Integration Feasibility

• Laravel Eloquent: Native integration via traits and query scopes; minimal boilerplate.
• Scout: Designed for coexistence but requires explicit aliasing to avoid naming conflicts (e.g., scopeDatabaseSearch).
• Filament: Plugin-based with macros for table/column search; global search requires resource-level configuration.
• Third-party builders: May conflict with existing search() methods (e.g., Corcel). Mitigation via applySearch() or trait aliasing.
• Database agnosticism: Works across MySQL, PostgreSQL, and SQLite but with varying LIKE behavior.

Technical Risk

• Performance degradation: Unindexed LIKE queries on large tables will impact response times. Requires proactive monitoring and Scout migration planning.
• Complex relation queries: Deeply nested morph relations (e.g., commentable:post.author.name) may generate verbose SQL, increasing query complexity.
• Cross-database edge cases: External relation limits (50 IDs) could exclude matches in high-cardinality scenarios. Requires testing with production-like data volumes.
• Scout migration: Switching from SQL to Scout search requires reindexing and potential query refactoring (e.g., replacing databaseSearch() with search()).
• Case sensitivity: Assumes default database collations; custom collations may yield unexpected results.

Key Questions

1. Scalability Needs:
   • What is the expected scale of searchable records per model? (e.g., <10K vs. >1M)
   • Are there plans to migrate to Scout for large datasets, and if so, what’s the timeline?
2. Performance Trade-offs:
   • Are there critical queries where LIKE performance is unacceptable, even with indexing?
   • Should pg_trgm (PostgreSQL) or full-text indexes be implemented as a fallback?
3. Relation Complexity:
   • How deeply nested are morph relations (e.g., user:post:author.name)? Will query generation become unwieldy?
   • Are cross-database relations frequent, and is the 50-ID cap sufficient?
4. Case Sensitivity:
   • Are there case-sensitive search requirements? If so, how will collations be standardized?
5. Scout Integration:
   • Should the package’s search() scope be aliased globally (e.g., databaseSearch()) to avoid ambiguity?
   • Will Filament’s global search use Scout or SQL? (Requires getGloballySearchableAttributes() alignment.)
6. Maintenance:
   • Who will monitor query performance and cross-database relation limits?
   • Is there a process for handling Scout migration across all searchable models?

Integration Approach

Stack Fit

• Laravel Core: Ideal for Eloquent-based applications with moderate search complexity.
• Scout Ecosystem: Complements Meilisearch/Algolia/Typesense for scalable full-text search.
• Filament: Native support for admin panels; reduces custom frontend development.
• Legacy Systems: Useful for applications already using Eloquent without Scout or dedicated search infrastructure.
• Microservices: Cross-database relation support enables searching across services without API calls.

Migration Path

1. Pilot Phase:
   • Start with a single high-impact model (e.g., Post or Product) to test SQL performance and relation queries.
   • Validate Filament integration for admin workflows.
2. Incremental Adoption:
   • Roll out to non-critical models first, monitoring query performance.
   • Replace manual where clauses with searchableColumns() where applicable.
3. Scout Migration:
   • Identify models exceeding performance thresholds (e.g., >10K records with frequent searches).
   • Implement Scout for these models, updating queries from databaseSearch() to search().
   • Use Scout’s searchableAs to maintain backward compatibility during transition.
4. Filament Global Search:
   • Configure getGloballySearchableAttributes() per resource, aligning with Scout or SQL search.
   • Test with real user queries to ensure relevance.

Compatibility

• Laravel Versions: Requires Laravel 10+ (PHP 8.2+). Check compatibility with existing Laravel version.
• Scout Providers: Test with all planned Scout backends (Meilisearch, Algolia, etc.) to ensure no conflicts.
• Database Drivers: Validate LIKE behavior across production databases (e.g., PostgreSQL pg_trgm vs. MySQL collations).
• Third-Party Packages:
  • Corcel/WordPress: Override search() in custom builders to delegate to applySearch().
  • Custom Query Builders: Ensure scopeSearch conflicts are resolved via trait aliasing.
• Filament Version: Confirm compatibility with the Filament version in use (e.g., macros may vary).

Sequencing

1. Trait Integration:
   • Add Searchable trait to models and define searchableColumns().
   • Test basic searches (Model::search('term')) and chained queries.
2. Filament Setup:
   • Add advancedSearchable() to table columns.
   • Register SearchableGlobalSearchProvider for global search.
3. Relation Testing:
   • Validate morph relations, cross-database queries, and nested paths (e.g., author.name).
   • Adjust externalLimit if needed for cross-database relations.
4. Performance Tuning:
   • Identify slow queries using Laravel Debugbar or Query Logger.
   • Implement Scout for models with poor performance.
5. Scout Migration:
   • Update models to use Scout’s Searchable trait alongside DatabaseSearchable.
   • Replace databaseSearch() with search() in application code.
6. Deprecation:
   • Phase out SQL searches for Scout-migrated models.
   • Deprecate databaseSearch() in favor of Scout’s search() where applicable.

Operational Impact

Maintenance

• Query Monitoring:
  • Set up Laravel Query Logger or New Relic to track LIKE query performance.
  • Alert on queries exceeding thresholds (e.g., duration >500ms or row scans >10K).
• Index Management:
  • Maintain indexes on filtered columns (e.g., tenant_id, status) to reduce LIKE scan scope.
  • For PostgreSQL, consider pg_trgm indexes for LIKE '%term%' queries.
• Scout Sync:
  • Monitor Scout index health and sync frequency for migrated models.
  • Schedule regular Scout index rebuilds if using Meilisearch/Typesense.
• Filament Updates:
  • Stay updated with Filament versions to ensure advancedSearchable() macro compatibility.
  • Test global search after Filament updates.

Support

• Developer Onboarding:
  • Document searchableColumns() conventions (e.g., relation paths, morph notation).
  • Provide examples for common use cases (e.g., cross-database relations, Scout migration).
• Troubleshooting:
  • Common issues:
    • Case sensitivity mismatches (debug collations).
    • Slow queries (log and optimize with Scout).
    • Cross-database relation limits (adjust externalLimit).
    • Scout conflicts (alias scopeSearch).
  • Create runbooks for performance degradation and Scout migration.
• Filament-Specific:
  • Train admin users on global search usage and column filtering.
  • Document getGloballySearchableAttributes() requirements per resource.

Scaling

• SQL Limits:
  • Expect performance degradation at ~10K–50K records per model with LIKE queries.
  • Plan Scout migration for models exceeding these thresholds.
• Scout Scaling:
  • Meilisearch/Typesense: Handle millions of records with sub-100ms latency.
  • Algolia: Higher cost but global low-latency search.
• Cross-Database:
  • Monitor externalLimit usage; increase if queries exclude too many