Es Lib Laravel Package

Getting Started

First Steps

1. Installation

   composer require awd-studio/es-lib
   

   Publish the config (if available) with:

   php artisan vendor:publish --provider="AwdStudio\EsLib\EsLibServiceProvider"
   

2. Basic Usage The package provides Elasticsearch utilities. Start by configuring it in config/es-lib.php:

   'connections' => [
       'default' => [
           'hosts' => ['http://localhost:9200'],
           'index' => 'your_app_index',
       ],
   ],
   

3. First Query Use the Elasticsearch facade to run a simple search:

   use AwdStudio\EsLib\Facades\Elasticsearch;
   
   $results = Elasticsearch::search('your_query', ['index' => 'your_app_index']);
   

Implementation Patterns

Common Workflows

1. Indexing Models Use the ElasticsearchModel trait to sync Laravel models with Elasticsearch:

   use AwdStudio\EsLib\Traits\ElasticsearchModel;
   
   class Product extends Model
   {
       use ElasticsearchModel;
   
       protected $esIndex = 'products';
   }
   

   Sync data on model events:

   Product::created(fn ($product) => $product->syncToEs());
   

2. Query Builder Chain methods for complex queries:

   $results = Elasticsearch::search('laptop')
       ->filter('price', '>=', 500)
       ->sortBy('created_at', 'desc')
       ->paginate(10);
   

3. Bulk Operations Use Elasticsearch::bulk() for batch indexing:

   $data = Product::all()->map(fn ($p) => $p->toEsArray());
   Elasticsearch::bulk($data, 'products');
   

Integration Tips

• Laravel Scout Alternative: Replace Scout’s Elasticsearch driver with this package for custom logic.
• Event Listeners: Hook into es-synced or es-failed events for post-sync actions.
• Middleware: Use EsLibMiddleware to inject Elasticsearch data into requests.

Gotchas and Tips

Pitfalls

1. Index Mapping Conflicts

   • Ensure your model’s toEsArray() returns fields matching the Elasticsearch mapping. Use Elasticsearch::index()->putMapping() to verify/update mappings.

2. Rate Limiting

   • Bulk operations may hit Elasticsearch limits. Use Elasticsearch::bulk()->chunk(500) to batch requests.

3. Connection Timeouts

   • Configure retries in config/es-lib.php:

     'retry' => [
         'max_attempts' => 3,
         'delay' => 100, // ms
     ],
     

Debugging

• Log Queries: Enable debug mode:

  Elasticsearch::debug(true); // Logs raw queries to storage/logs/es.log
  

• Test Locally: Use Dockerized Elasticsearch (e.g., docker run -p 9200:9200 elasticsearch:8).

Extension Points

1. Custom Analyzers Extend the Analyzer class to add domain-specific tokenizers:

   Elasticsearch::analyzer()->custom('custom_analyzer', [
       'type' => 'custom',
       'tokenizer' => 'standard',
       'filter' => ['lowercase', 'asciifolding'],
   ]);
   

2. Hooks Override syncToEs() in your model to add pre/post-processing:

   protected function prepareForEs()
   {
       $this->esData['slug'] = Str::slug($this->name);
   }
   

3. Async Processing Use Laravel Queues to offload syncs:

   Product::created(fn ($p) => SyncToEsJob::dispatch($p));