Weave Code
Laravel Elasticsearch Laravel Package
mailerlite/laravel-elasticsearch
A Laravel wrapper for Elasticsearch that makes indexing and searching Eloquent models simple, with a fluent query builder, customizable index mapping, and support for multiple Elasticsearch connections.
An easy way to use the official Elastic Search client in your Laravel applications.
Frequently asked questions about Laravel Elasticsearch
- How do I install mailerlite/laravel-elasticsearch in a Laravel application?
- Install it with Composer using composer require mailerlite/laravel-elasticsearch. The package ships a service provider and facade that are auto-discovered by Laravel, so no manual registration is normally required. Publish the configuration file with the vendor:publish command, then set your Elasticsearch hosts and credentials in your environment file. After that you can resolve the client through the facade or inject it directly.
- Which Elasticsearch versions does mailerlite/laravel-elasticsearch 12.x support?
- Release 12.0.0 was cut specifically to support Elasticsearch 8, following the package's convention of matching its major version to the upstream Elasticsearch major (11.x for ES 7, 12.x for ES 8). The release notes do not state whether ES 7 support was retained alongside ES 8, so treat that assumption as unverified. Confirm the compatibility matrix with the maintainer or a spike before committing to it. If you are still on an Elasticsearch 7 cluster, pin to 11.3.0 instead.
- Can I use this package against an Elasticsearch 7 cluster?
- Yes, but only on the 11.x line, with 11.3.0 being the recommended pin. Version 12.0.0 aligns with Elasticsearch 8 and does not ship a migration guide, so running it against an ES 7 cluster is not a supported path. Treat 12.x as deliberately deferred until your cluster has been upgraded. Do not combine the cluster upgrade and the package upgrade in a single change.
- How do I index an Eloquent model into Elasticsearch with this package?
- The package provides a model abstraction so an Eloquent model can declare its index name and mapping and then be indexed directly. You define the index configuration on the model and call the provided indexing methods to create the index and push documents. Searching returns hydrated Eloquent models rather than raw arrays, which keeps your application code close to normal Eloquent usage.
- How do I define a custom index mapping in laravel-elasticsearch?
- Mappings are declared on the model or in the package configuration as a standard Elasticsearch properties array, so you control field types, analyzers, and any other mapping settings. Because Elasticsearch 8 removed mapping types from index APIs, verify that your mapping definition does not rely on type-qualified URLs or typed index creation. Once the mapping is defined, create the index through the package rather than by hand so the definition stays in version control.
- How does the fluent query builder work for searching models?
- The package exposes an Eloquent-style query builder on top of the official Elasticsearch client, so you chain methods to build the query body and then retrieve results as model instances. This keeps common queries readable without dropping into raw Elasticsearch DSL for every call. For complex aggregations or unusual endpoints you can still reach the underlying client directly.
- Does mailerlite/laravel-elasticsearch support multiple Elasticsearch connections?
- Yes, the package supports multiple connections configured in its config file, and you can select a connection per query or model. This is useful when you separate indices by environment, tenant, or cluster. Each connection can carry its own hosts, credentials, and TLS settings, which matters once Elasticsearch 8 security defaults are enabled.
- How do I configure authentication and TLS for Elasticsearch 8 with this package?
- Elasticsearch 8 enables TLS and authentication by default, so your hosts must use https and you must supply credentials or an API key. Point the package config at your certificate authority bundle if you use a private CA. Code that worked against an unsecured local Elasticsearch 7 node will typically fail at connection or index creation time, and the resulting errors often surface far from the config change that caused them. Test against a secured staging cluster rather than a bare local node.
- How should I test this package's Elasticsearch integration before going to production?
- Stand up an Elasticsearch 8 staging cluster with security enabled so it is representative of production, then run your index creation, mapping, and query paths against it. Mocked clients used in CI will not catch ES 8 behavioral changes such as TLS requirements or removed mapping types. Capture a diff of any query or mapping failures and inventory every index and query your application issues before scheduling the upgrade.
- What are the alternatives to mailerlite/laravel-elasticsearch?
- You can use the official elasticsearch/elasticsearch PHP client directly and manage the service binding yourself, which removes a layer but also removes the Eloquent model abstraction. Laravel Scout with an Elasticsearch driver is another option if you want a framework-native search abstraction. This package is the right fit when you want a thin Laravel wrapper plus Eloquent-style indexing and a fluent query builder without Scout's opinionated model.
Weaver
How can I help you explore Laravel packages today?