Elastic Bridge: query in stile Eloquent per Elasticsearch e OpenSearch

Elastic Bridge è un package Laravel di Agyenim Boateng per interrogare Elasticsearch e OpenSearch con un'API in stile Eloquent. Si definisce una classe per un indice, poi si concatenano metodi PHP per la ricerca full-text e i filtri senza scrivere a mano il DSL JSON.

Se hai già usato un query builder PHP fluente per Elasticsearch, la sintassi delle query ti risulterà familiare. Elastic Bridge offre anche il casting dei documenti, accessor e mutator, l'indicizzazione in blocco e query su più indici.

Definisci un bridge per il tuo indice

Il package chiama le sue classi model "bridges". Generane uno con Artisan:

php artisan make:bridge HotelRoom

Ogni bridge estende la classe base del package. Puoi impostare esplicitamente il suo indice:

namespace App\\Bridges;

use Lacasera\\ElasticBridge\\ElasticBridge;

class HotelRoom extends ElasticBridge
{
protected $index = 'hotel-rooms';
}

I bridge supportano una proprietà $casts per convertire gli attributi dei documenti, incluse date ed enum. Accessor e mutator permettono di modificare i valori durante la lettura o l'assegnazione degli attributi, usando la classe Attribute di Laravel.

Combina ricerca full-text e filtri

Una ricerca di camere può combinare un match sulla città con un filtro sulla valuta e un limite di prezzo:

use App\\Bridges\\HotelRoom;

$rooms = HotelRoom::asBoolean()
->mustMatch('city', 'accra')
->filterByTerm('code', 'usd')
->filterByRange('price', 500, 'lte')
->orderBy('price', 'ASC')
->cursorPaginate(15)
->get(['name', 'price', 'code']);

La distinzione tra mustMatch() e filterByTerm() segue la struttura delle query del motore di ricerca: il primo costruisce una clausola match, mentre il secondo aggiunge un filtro term esatto. I mapping dei campi determinano comunque come vengono cercati i documenti.

Per una ricerca su più campi, usa multiMatch():

$rooms = HotelRoom::multiMatch(
field: ['advertiser', 'service_type'],
query: 'hotel',
)->get();

La documentazione sulla ricerca full-text spiega i tipi di query supportati. Nella v2, multiMatch() e matchPhrase() si annidano automaticamente all'interno di una query boolean. Un match() autonomo usa asRaw() o asMatch(); all'interno di una query boolean, usa mustMatch() o shouldMatch().

La paginazione basata su cursor usa search_after e richiede un ordinamento deterministico. La collection restituita fornisce i valori di ordinamento successivi e precedenti tramite links(), che si passano a una successiva chiamata cursorPaginate().

Recupera documenti e aggregazioni insieme

Puoi chiamare metodi di aggregazione scalari come avg(), sum() e count(), oppure associare un'aggregazione a una query sui documenti:

$rooms = HotelRoom::asBoolean()
->mustMatch('city', 'accra')
->withAggregate('avg', 'price')
->get();

$averagePrice = $rooms->priceAvg();

Nella v2, i risultati delle aggregazioni appartengono all'istanza della collection restituita. Set di risultati separati mantengono i propri valori di aggregazione, anche nei worker di lunga durata. Il package restituisce anche un oggetto Stats per stats() e una collection di oggetti bucket per histogram().

Testa senza un cluster di ricerca

Il metodo fake() del package fornisce una risposta di ricerca per entrambi i backend. Puoi ispezionare la query generata con toQuery():

public function test_builds_currency_filter(): void
{
HotelRoom::fake([
'hits' => [
'total' => ['value' => 0, 'relation' => 'eq'],
'hits' => [],
],
]);

$query = HotelRoom::asBoolean()
->filterByTerm('code', 'usd')
->toQuery();

$this->assertSame([
'query' => [
'bool' => [
'filter' => [
['term' => ['code' => 'usd']],
],
],
], $query);
}

Questo verifica la query che la tua applicazione costruisce senza richiedere un'istanza Elasticsearch o OpenSearch in esecuzione. La documentazione sui test illustra l'API della connessione fake.

Installazione e configurazione del backend

I requisiti documentati sono PHP 8.2 o 8.3, Laravel 10, 11 o 12, ed Elasticsearch 8.x o OpenSearch 2.x.

composer require lacasera/elastic-bridge
php artisan vendor:publish --tag="elastic-bridge-config"

Imposta SEARCH_DRIVER su elasticsearch o opensearch e configura la connessione in config/elasticbridge.php. Entrambi i driver usano la stessa API fluente per le query. Le opzioni di autenticazione includono basic auth e API key, oltre ad AWS SigV4 per OpenSearch con la dipendenza opzionale dell'AWS SDK.

Il package include anche linee guida e una skill di sviluppo per il supporto alle skill di Laravel Boost. Esegui php artisan boost:install in un progetto che usa Boost per rendere disponibili le indicazioni del package al tuo agente di coding.

Puoi trovare le istruzioni di configurazione e il riferimento API nella documentazione di Elastic Bridge e il package con licenza MIT su GitHub.