Explorer Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • Laravel Scout Integration: Seamlessly replaces Laravel Scout’s default Elasticsearch driver, leveraging Laravel’s existing searchable traits (Searchable) and Scout’s query builder.
  • Hexagonal Architecture: Clear separation of Application, Domain, and Infrastructure layers (e.g., Explored interface, FakeResponse for testing) aligns with modern Laravel best practices and enables testability.
  • Elasticsearch Abstraction: Provides a fluent, Laravel-native API for complex Elasticsearch queries (e.g., nested fields, aggregations, custom syntax) without requiring raw JSON payloads.
  • Index Aliases: Supports zero-downtime deployments via read/write/history aliases, critical for production-grade search systems.

• Fit for Use Cases:

  • Content-Heavy Apps: Ideal for blogs, e-commerce (product search), or document management where advanced sorting/filtering (e.g., nested author.name) is needed.
  • Analytics/Reporting: Aggregations and custom queries enable metrics like "top tags by engagement" or "search trends."
  • Hybrid Search: Combines full-text search with structured filters (e.g., Term queries for categories).

• Gaps:

  • Partial Aggregation Support: Not all Elasticsearch aggregation types are implemented (e.g., geo_aggregations). Requires custom SyntaxInterface implementations.
  • No Built-in Async Indexing: Relies on Scout’s default indexing behavior (synchronous by default). For large datasets, consider integrating with Laravel Queues or Scout’s toSearchableArray() optimizations.

Integration Feasibility

• Laravel Compatibility:

  • Scout Dependency: Requires Laravel Scout (v8+). If using Scout’s meilisearch or algolia drivers, migration is straightforward.
  • Model Changes: Minimal—add use Searchable and optionally Explored interface or publish config for mappings.
  • Query Builder: Replaces Scout’s where() with Explorer’s filter(), must(), etc., but retains Laravel’s cursor()/paginate() methods.

• Elasticsearch Version:

  • Assumes Elasticsearch 7.x/8.x. Verify compatibility with your cluster version (e.g., keyword vs. text field handling in mappings).
  • Mapping Control: Explicit mappings (via config or mappableAs()) are recommended to avoid Elasticsearch’s dynamic inference pitfalls (e.g., date vs. string conflicts).

• Testing Support:

  • Fake Responses: FakeResponse mocks Elasticsearch API calls, enabling unit tests without a live cluster. Example in docs shows integration with Laravel’s instance() mocking.
  • Feature Tests: Supports Laravel’s HTTP testing (e.g., post('api/search')) with mocked responses.

Technical Risk

• Migration Complexity:
  • Low for Scout Users: If already using Scout, swapping drivers is akin to changing a config value ('driver' => 'explorer').
  • High for Custom Scout Logic: If extending Scout’s Engine or Builder classes, refactor to use Explorer’s SyntaxInterface or query properties.
• Performance Risks:
  • Nested Queries: Deeply nested fields (e.g., author.tags.subtags) may degrade performance. Monitor query execution time via Elasticsearch’s _explain API.
  • Pagination: Elasticsearch’s default from/size pagination is inefficient for deep pagination. Use search_after or scroll APIs for large datasets (Explorer doesn’t expose these natively; may need custom syntax).
• Schema Drift:
  • Mapping Changes: Altering mappableAs() or config requires reindexing. Use aliases (prune_old_aliases: false) during development to preserve old indices.
• Dependency Lock:
  • Scout Version: Explorer’s last release (2026-03-24) may lag behind Laravel Scout updates. Test with your Scout version.

Key Questions

1. Elasticsearch Cluster:
   • Are you using a managed service (e.g., AWS OpenSearch) or self-hosted? Managed services may require adjustments for IAM roles or VPC configurations.
2. Data Volume:
   • How many documents will be indexed? For >1M documents, consider shard allocation and bulk indexing strategies.
3. Query Complexity:
   • Will you need unsupported aggregations or custom analyzers? Assess effort to implement via SyntaxInterface.
4. CI/CD:
   • How will you test mapping changes? Use FakeResponse for unit tests and integrate Elasticsearch’s _validate/query API in deployment pipelines.
5. Monitoring:
   • Do you have observability for Elasticsearch queries (e.g., slow logs, cluster health)? Explorer lacks built-in metrics; pair with tools like Elasticsearch’s profile: true or APM.

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Scout Users: Zero-config swap for elasticsearch driver. Replace config/scout.php:

    'driver' => 'explorer',
    

  • Non-Scout Apps: Requires adding Scout and Explorer as dependencies. Useful if already using Scout for other drivers (e.g., Algolia fallback).
• Elasticsearch Stack:
  • Compatibility: Works with any Elasticsearch 7.x/8.x cluster. Test with your version’s mapping types (e.g., date vs. date_nanos).
  • Security: Supports Elasticsearch’s native security (e.g., API keys) via Scout’s client configuration.
• Testing Stack:
  • Unit Tests: FakeResponse replaces Elasticsearch HTTP calls. Store mock responses in tests/Support/Elastic/Responses/.
  • Feature Tests: Mock the ElasticClientFactory to simulate API responses (as shown in docs).

Migration Path

1. Assessment Phase:
   • Audit existing Scout queries. Identify custom logic (e.g., ScoutEngine extensions) that may need refactoring.
   • Review current Elasticsearch mappings. Update mappableAs() or config to match Explorer’s syntax.
2. Dependency Setup:

   composer require jeroen-g/explorer laravel/scout:"^8.0"
   

3. Configuration:
   • Publish Explorer’s config:

     php artisan vendor:publish --tag=explorer.config
     

   • Update config/explorer.php with your indexes and mappings.
4. Model Updates:
   • Add use Searchable to models. Implement Explored interface or use config-based mappings.
   • Example:

     class Post extends Model implements Explored {
         use Searchable;
     
         public function mappableAs(): array {
             return ['title' => 'text', 'published_at' => 'date'];
         }
     }
     

5. Query Migration:
   • Replace Scout’s where() with Explorer’s filter()/must():

     // Before (Scout)
     Post::search('query')->where('published', true)->get();
     
     // After (Explorer)
     Post::search('query')->filter(new Term('published', true))->get();
     

   • For nested queries, use dot notation:

     Post::search('query')->must(new Nested('author', new Matching('author.name', 'John')))->get();
     

6. Testing:
   • Write FakeResponse-based unit tests for critical queries.
   • Update feature tests to mock ElasticClientFactory.
7. Deployment:
   • Reindex data using Scout’s scout:import or Explorer’s alias system:

     php artisan scout:import "App\Models\Post"
     

   • Enable aliases for zero-downtime updates:

     'prune_old_aliases' => env('APP_ENV') !== 'production',
     

Compatibility

• Laravel Versions: Tested with Laravel 8+. For Laravel 9/10, check for breaking changes in Scout’s Searchable trait.
• Elasticsearch Versions: Verify compatibility with your cluster’s version (e.g., keyword vs. text in mappings).
• Custom Scout Logic:
  • If extending Scout’s Builder or Engine, refactor to use Explorer’s SyntaxInterface or query properties.
  • Example: Convert a custom ScoutEngine to a SyntaxInterface implementation.

Sequencing

1. Phase 1: Non-Critical Models
   • Start with low-traffic models (e.g., Post, Product) to validate Explorer’s performance and query behavior.
2. Phase 2: Complex Queries
   • Migrate models using nested fields, aggregations, or custom syntax.
3. Phase 3: Full Rollout
   • Update remaining models and deploy with aliases enabled.
4. Phase 4: Optimization
   • Analyze slow queries using Elasticsearch’s _explain API.
   • Adjust mappings (e.g., keyword vs. text) based on query patterns.

Operational Impact