Explorer Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require jeroen-g/explorer
   php artisan vendor:publish --tag=explorer.config
   

   Update config/scout.php to set 'driver' => 'elastic'.

2. Configure Elasticsearch:

   • Set up Elasticsearch (e.g., via Docker using the provided docker-compose.yml).
   • Define your index in config/explorer.php:

     'indexes' => [
         'posts_index' => [
             'properties' => [
                 'id' => 'keyword',
                 'title' => 'text',
             ],
         ],
     ],
     

3. First Use Case:

   • Import data into Elasticsearch:

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

   • Search using Scout:

     $results = App\Models\Post::search('query')->get();
     

Implementation Patterns

Workflows

1. Index Management:

   • Create/Update: Use scout:import for initial setup or elastic:update for aliased indexes.
   • Delete: Use scout:delete-index to drop an index.
   • Test Searches: Use elastic:search for ad-hoc queries:

     php artisan elastic:search "App\Models\Post" "query" --fields=title,body
     

2. Model Integration:

   • Ensure models implement Scout’s toSearchableArray():

     public function toSearchableArray()
     {
         return [
             'title' => $this->title,
             'body' => $this->body,
         ];
     }
     

3. Advanced Queries:

   • Leverage Scout’s query builder for Elasticsearch-specific features:

     $results = Post::search('query')
         ->where('published_at', '>', now()->subYear())
         ->orderBy('views', 'desc')
         ->get();
     

4. Pagination:

   • Use Scout’s built-in pagination:

     $results = Post::search('query')->paginate(10);
     

Integration Tips

• Aliases: Use elastic:update for zero-downtime index rotations.
• Sorting: Override default score-based sorting:

  Post::search('query')->orderBy('created_at', 'desc');
  

• Aggregations: Use Explorer’s extensions for faceted search:

  $results = Post::search('query')->withAggregations(['tags']);
  

Gotchas and Tips

Pitfalls

1. Mapping Conflicts:

   • Elasticsearch may auto-generate mappings if not explicitly defined. Use config/explorer.php to enforce schema consistency.
   • Fix: Delete and recreate the index if mappings are incorrect.

2. Connection Issues:

   • Ensure Elasticsearch is running and accessible (e.g., localhost:9200).
   • Debug: Use ElasticEngine::debug()->json() to inspect raw queries.

3. Performance:

   • Avoid indexing large fields (e.g., raw HTML) without ignore_above.
   • Tip: Use text for searchable fields and keyword for exact matches.

4. Aliases:

   • Forgetting to update aliases after index changes can break searches.
   • Fix: Always run elastic:update after modifying indices.

Debugging

• Logs: Enable logging via EXPLORER_ELASTIC_LOGGER_ENABLED=true and configure in explorer.php:

  'logger' => \Illuminate\Support\Facades\Log::channel('daily'),
  

• Fake Responses: Mock Elasticsearch in tests:

  $this->instance(ElasticClientFactory::class, ElasticClientFactory::fake($fakeResponse));
  

Extension Points

1. Custom Mappings:

   • Extend config/explorer.php for complex types (e.g., nested objects):

     'properties' => [
         'tags' => [
             'type' => 'nested',
             'properties' => ['name' => 'keyword'],
         ],
     ],
     

2. Preprocessing:

   • Use toSearchableArray() to transform data before indexing:

     public function toSearchableArray()
     {
         return [
             'title' => strtolower($this->title),
         ];
     }
     

3. Advanced Queries:

   • Use Explorer’s QueryBuilder for custom DSL:

     $query = Post::search('query')->query(function ($q) {
         return $q->bool()->must([
             'match' => ['title' => 'search term'],
         ]);
     });
     

Config Quirks

• SSL/TLS: For Elasticsearch 8+, ensure ssl.verify is configured (default: true).
• Environment Variables: Override connection settings via .env:

  EXPLORER_HOST=elasticsearch.example.com
  EXPLORER_PORT=9200