Stretch - Laravel Elasticsearch Query Builder

A fluent, intuitive Laravel package for building Elasticsearch queries with comprehensive support for all major query types, aggregations, and advanced features.

Installation

Install the package via Composer:

composer require seclock/stretch

Publish the configuration file:

php artisan vendor:publish --tag="stretch-config"

Configuration

Configure your Elasticsearch connection in your .env file:

ELASTICSEARCH_HOST=localhost:9200
ELASTICSEARCH_USERNAME=your_username
ELASTICSEARCH_PASSWORD=your_password

Basic Usage

use JayI\Stretch\Facades\Stretch;

// Full-text search
$results = Stretch::index('posts')
    ->match('title', 'Laravel')
    ->sort('created_at', 'desc')
    ->size(20)
    ->execute();

// Bool query with filters
$results = Stretch::index('posts')
    ->bool(function ($bool) {
        $bool->must(fn($q) => $q->match('title', 'Laravel'));
        $bool->filter(fn($q) => $q->term('status', 'published'));
        $bool->filter(fn($q) => $q->range('created_at')->gte('2024-01-01'));
    })
    ->execute();

// Aggregations
$results = Stretch::index('orders')
    ->aggregation('by_category', fn($agg) =>
        $agg->terms('category.keyword')
            ->size(10)
            ->subAggregation('avg_total', fn($sub) => $sub->avg('total'))
    )
    ->execute();

Documentation

Document	Description
Configuration	Connection setup, all config options, env vars, multiple connections
Queries	All query types: match, multi_match, term-level, range, bool, compound, geo, span, percolate, count
Scoring	rank_feature, distance_feature, script_score, function_score (decay, field_value_factor, random)
Search Tuning	min_score, rescore, runtime fields, field selection, suggesters, request routing
Aggregations	Bucket, metric, geo, and pipeline aggregations, sub-aggregations, raw escape hatch
Hybrid Search	kNN vector search, server-side embeddings, Retriever API, RRF
Multi-Search	Execute multiple queries in a single request
Caching	Cache setup, TTL, stale-while-revalidate, cache stores
Index Management	Index/document CRUD, update-by-query, PIT, analyze/explain/termvectors, bulk, pipelines, inference, ML
Pagination	ElasticPaginator, deep paging with search_after + point-in-time, Scroll API
Synonyms	Manage synonym sets and rules via the Synonyms API

Testing

composer test

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please message instead of using the issue tracker.

License

The MIT License (MIT). Please see License File for more information.