Scoutify Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Scout Integration: Leverages Laravel Scout (Meilisearch, Algolia, Typesense, or Database) for search, aligning with modern Laravel search patterns. Reduces custom search logic and maintenance.
  • Livewire UI: Provides a production-ready, keyboard-driven (⌘K/Ctrl+K) modal with WCAG AA compliance, reducing frontend development effort.
  • Multi-model Support: Auto-discovers and groups results by model type, simplifying complex search UIs (e.g., dashboards with users, articles, products).
  • Extensibility: Hooks for customizing queries (globalSearchBuilder), visibility rules, and previews (HasGlobalSearchPreview) allow tailored behavior without forking.
  • Dark Mode & i18n: Built-in support for theming and localization reduces UI/UX fragmentation.
  • File Previews: Native support for PDFs/images/videos in the modal (via HasGlobalSearchPreview) eliminates need for third-party libraries.

• Cons:

  • Scout Dependency: Tight coupling to Scout may limit flexibility if the team later migrates to a non-Scout search solution (e.g., Elasticsearch).
  • Livewire Overhead: Requires Livewire (v3/4) and may introduce complexity for teams not already using it.
  • Auto-Discovery: While convenient, auto-registering models under app/Models/ could lead to unintended behavior if the directory structure evolves (e.g., namespaced models).
  • Session-Based History: Recent searches are session-scoped, which may not suit multi-device or shared-session use cases (e.g., admin panels).

Integration Feasibility

• Laravel Compatibility: Supports Laravel 11–13 and Scout 11–12, ensuring compatibility with modern stacks. Minimal risk for teams already using these versions.
• Livewire Dependency: Requires Livewire (v3/4), which is widely adopted but may require setup for teams not using it.
• Scout Drivers: Supports Meilisearch (default), Algolia, Typesense, or Database. Teams already using Scout will face low friction; others may need to evaluate driver trade-offs (e.g., Meilisearch for cost, Algolia for enterprise features).
• Blade Icons: Relies on Blade Icons for UI icons. Teams using Tailwind CSS will benefit; others may need to install a compatible pack (e.g., heroicon).
• Authorization: Integrates with Laravel Gates, Spatie Permissions, and custom logic. Teams using Spatie will see seamless adoption; others may need to adapt existing auth systems.

Technical Risk

• Low:
  • Installation: The scoutify:install command automates driver setup and config publishing, reducing manual errors.
  • Model Registration: The scoutify:searchable command auto-edits model files, though --dry-run mitigates risk.
  • UI Placement: Clear documentation on modal placement (root layout level) prevents common Livewire initialization issues.
• Medium:
  • Customization Depth: Overriding globalSearchBuilder or visibility rules requires PHP knowledge. Teams unfamiliar with Scout’s query builder may need training.
  • File Previews: Preview functionality (e.g., S3 pre-signed URLs) depends on storage driver capabilities. Teams using unsupported disks (e.g., local) may need custom logic.
  • Performance: Scout queries and Livewire modal rendering could impact performance for large datasets or slow drivers (e.g., Database driver with LIKE searches).
• High:
  • Scout Driver Quirks: Meilisearch’s word-boundary prefix search may require workarounds for infix matching (e.g., overriding globalSearchBuilder).
  • Livewire State Management: Complex interactions (e.g., nested Livewire components) could lead to state conflicts if not handled carefully.
  • Authorization Edge Cases: Custom visibility rules might interact unpredictably with existing auth systems (e.g., Spatie Permissions vs. Gates).

Key Questions

1. Search Requirements:
   • Does the team need infix/substring search (e.g., "ano" in "Mariano")? If so, is the Database driver or Meilisearch workarounds acceptable?
   • Are there performance constraints (e.g., <50ms response time) that could limit Scout driver choices?
2. UI/UX:
   • Should recent searches persist across sessions (e.g., in a database) instead of being session-scoped?
   • Are there existing UI components (e.g., search bars) that conflict with Scoutify’s triggers?
3. Authorization:
   • Does the team use Spatie Permissions or custom auth systems? If not, will the default "secure" mode suffice?
   • Are there models requiring fine-grained visibility rules (e.g., role-based access)?
4. Infrastructure:
   • Is Scout already in use? If not, what are the trade-offs of adding it (cost, maintenance, scalability)?
   • Are file previews required for specific model types (e.g., documents, images)?
5. Maintenance:
   • Who will handle Scout index updates (e.g., scoutify:import) in production? Will a queue (e.g., Laravel Horizon) be needed for large datasets?
   • Are there plans to extend Scoutify (e.g., faceted search, synonyms)? If so, is the package’s extensibility sufficient?

Integration Approach

Stack Fit

• Core Stack:

  • Laravel: Native fit for Laravel 11–13 apps using Scout and Livewire.
  • Scout: Required for search functionality. Compatible with Meilisearch (recommended), Algolia, Typesense, or Database.
  • Livewire: Mandatory for the modal UI. Teams not using Livewire will need to adopt it (v3/4).
  • Tailwind CSS: Scoutify uses Tailwind v4 utilities. Teams using other CSS frameworks (e.g., Bootstrap) may need to override styles.
  • Blade Icons: Optional but recommended for icons. Teams can use any Blade Icons pack (e.g., heroicon, tabler).
  • Spatie Permissions: Optional but enables advanced authorization rules (e.g., ->permission(), ->role()).

• Compatibility Notes:

  • PHP 8.1+: Required for Laravel 11–13 and Scout 11–12.
  • JavaScript: Uses Alpine.js for keyboard events (e.g., ⌘K). No additional JS libraries required.
  • Storage: File previews require compatible storage (e.g., S3 for pre-signed URLs; local storage falls back to signed routes).

Migration Path

1. Preparation:

   • Audit existing search implementations (e.g., custom queries, third-party packages) for conflicts.
   • Decide on a Scout driver (e.g., Meilisearch for cost/performance, Algolia for enterprise features).
   • Install required dependencies:

     composer require matheusmarnt/scoutify laravel/scout meilisearch/meilisearch-php
     

   • Configure Scout in .env:

     SCOUT_DRIVER=meilisearch
     MEILISEARCH_HOST=http://localhost:7700
     

2. Installation:

   • Run the installer:

     php artisan scoutify:install
     

     • Select a Scout driver (follow prompts to install its PHP client).
     • Publish configs:

       php artisan vendor:publish --provider="Matheusmarnt\Scoutify\ScoutifyServiceProvider"
       

   • Configure config/scoutify.php and config/scout.php as needed.

3. Model Integration:

   • Register models for global search:

     php artisan scoutify:searchable
     

     • Use --all to register all models under app/Models/ or select individually.
     • Review changes with --dry-run first.
   • Customize model behavior (optional):
     • Override globalSearchTitle(), globalSearchSubtitle(), etc., in registered models.
     • Implement HasGlobalSearchVisibility for custom auth rules.
     • Implement HasGlobalSearchPreview for file previews.
   • Import models into Scout:

     php artisan scoutify:import
     

     • For large datasets, consider queuing this task (e.g., with Laravel Horizon).

4. UI Integration:

   • Add triggers to your layout (e.g., resources/views/layouts/app.blade.php):

     <!-- Desktop trigger (lg+) -->
     <x-scoutify::gs.trigger class="hidden lg:inline-flex" />
     
     <!-- Mobile trigger -->
     <x-scoutify::gs.trigger-mobile />
     
     <!-- Modal (must be at root, after {{ $slot }}) -->
     {{ $slot }}
     <livewire:scoutify::modal />
     

   • Customize appearance via Scoutify’s fluent theme API (e.g.,