Laravel Scout Elasticsearch Laravel Package

Getting Started

Install the package with Composer and configure Laravel Scout to use the Elasticsearch driver:

composer require rapidez/laravel-scout-elasticsearch

Publish the package config (if applicable) and set your Scout driver in config/scout.php or via .env:

SCOUT_DRIVER=elasticsearch
ELASTICSEARCH_HOSTS=localhost:9200

Add the Laravel\Scout\Searchable trait to a model, then import existing records and run your first search:

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

Post::search('laravel')->get();

Start by reading the package README and the ElasticsearchEngine class to understand supported query methods and configuration options. The first use case is usually adding full-text search to a resource without managing Elasticsearch queries directly.

Implementation Patterns

• Use Scout’s fluent API (search(), where(), orderBy(), paginate()) as you would with other drivers; the package translates calls into Elasticsearch queries.
• Customize indexed data by overriding toSearchableArray() on your models. Keep the array flat and include only searchable/filterable fields.
• For bulk indexing, use php artisan scout:import with chunking (--chunk=500) to avoid memory issues. For incremental updates, Scout’s model events handle searchable()/unsearchable() automatically.
• Queue indexing in production by setting SCOUT_QUEUE=true in .env. This offloads index writes to workers and keeps HTTP responses fast.
• When filtering, you can pass arrays to where() (e.g., ->where('status', ['published', 'draft'])). As of 1.1.1, array arguments are safely handled without key-access errors.
• For complex Elasticsearch-specific queries, check whether the package exposes a raw query method (e.g., ->query()) or extend the engine. Many teams wrap custom query building in a repository or scope.
• Define explicit index mappings and settings for production rather than relying on dynamic mapping. Publish and edit the package’s index configuration if provided, or use Elasticsearch’s API directly before importing.

Gotchas and Tips

• The 1.1.1 release fixes a bug where where clauses with array values could throw errors when accessing keys. If you previously passed arrays to where(), upgrade to avoid unexpected exceptions.
• Ensure your Elasticsearch version matches the package’s requirements. Check composer.json for version constraints and test against your cluster before deploying.
• Scout’s default index name is derived from the model’s table. In multi-tenant or multi-environment setups, override searchableAs() to avoid collisions.
• Soft-deleted models are not automatically removed from the index. Override searchable() or use model observers to call unsearchable() when soft deleting.
• Debugging: enable Scout logging or use Laravel Telescope to inspect generated queries. For Elasticsearch-specific issues, call ->toSearchableArray() on a model and compare with the indexed document, or use Kibana/Dev Tools to run the query directly.
• Config quirks: the elasticsearch driver must be set in config/scout.php; environment variables like ELASTICSEARCH_HOSTS are read by the package. Clear config cache after changes (php artisan config:clear).
• Extension points: you can bind a custom engine implementation in a service provider, or extend the package’s engine class to add methods. Model observers and Scout macros are also useful for cross-cutting concerns.
• Always test index changes in a staging environment. Reindexing (scout:flush + scout:import) is required after mapping changes; plan for downtime or use aliases for zero-downtime reindexing.