- How do I migrate from Laravel Scout’s default Elasticsearch driver to jeroen-g/explorer?
- Replace the Scout driver in your `config/scout.php` with `jeroen-g/explorer` and run `php artisan scout:import`. The package extends Scout’s existing `Searchable` trait, so no changes are needed to your models unless you use custom mappings or aggregations. Always back up your Elasticsearch indices before switching drivers.
- Does this package support Elasticsearch 7.x or only 8.x?
- The package is optimized for Elasticsearch 8.x but may work with 7.x with minor adjustments. Check the Elasticsearch PHP client version (v8+) and ensure your cluster supports the required APIs. Test thoroughly, as breaking changes (e.g., removal of the `_type` field) could affect queries or mappings.
- Can I use this for internal admin dashboards with custom filters and actions?
- Yes, the package includes a built-in explorer UI with search, filters, sorting, and pagination. You can extend it with custom actions (e.g., bulk updates) by leveraging Scout’s `Searchable` trait and Explorer’s query builders. The `ExplorerServiceProvider` offers hooks for further customization.
- How do I handle nested data (e.g., user.posts.author) in Elasticsearch?
- Use the `Nested` query builder or define nested mappings in your model’s `mappableAs()` method. Avoid deep nesting for performance; consider flattening or using `object` mappings instead. The package supports both nested and object types, but nested queries require careful indexing (e.g., `nested: true` in mappings).
- What’s the best way to test this package without a real Elasticsearch cluster?
- Use the `FakeResponse` system provided by the package to mock Elasticsearch responses in unit tests. Configure it in your `phpunit.xml` or test case setup to return predefined JSON responses. For integration tests, use Dockerized Elasticsearch or Laravel’s `HttpTests` with mocked HTTP responses.
- Will this work with Laravel 10+ and Scout 8.x?
- Yes, the package is designed for Laravel 9+ and Scout 8.x. Check the package’s `composer.json` for the latest Laravel/Scout version support. If using Laravel 10, ensure your `config/scout.php` driver configuration matches the package’s requirements. No major breaking changes are expected for these versions.
- How do I configure index aliases for zero-downtime deployments?
- Define aliases in your `config/explorer.php` under the `aliases` key, mapping your index name to an alias (e.g., `posts_v1`). Use the `elastic:update` artisan command to apply changes. The package handles alias updates atomically, but monitor your Elasticsearch cluster for failures during deployments.
- Are there performance limitations with large datasets (e.g., 1M+ records)?
- Elasticsearch’s default `search_after` pagination avoids the 10,000-hits limit, but deep pagination (e.g., offset > 100,000) can impact performance. Use `keyset` pagination or runtime fields for large datasets. Monitor query latency and consider increasing heap size or shard count if needed.
- Can I add custom aggregations (e.g., percentiles, geo_aggregations) not included by default?
- Yes, extend the `AggregationBuilder` or use raw Elasticsearch queries via the `ElasticClient`. The package provides a `RawAggregation` builder for unsupported types. For geo-aggregations, ensure your Elasticsearch cluster has the `geoip` plugin installed and configure the relevant mappings.
- What happens if Elasticsearch is down? Does Scout fall back to the database?
- The package does not automatically fall back to Scout’s default driver. Configure a retry mechanism (e.g., Laravel’s `retry` helper) or implement a custom fallback in your `Searchable` model. For critical applications, use a circuit breaker pattern to avoid cascading failures.