From dea4c883cb856e37896585a756fbede058511bc8 Mon Sep 17 00:00:00 2001 From: Jay Fletcher <5743488+jayjfletcher@users.noreply.github.com> Date: Mon, 9 Nov 2026 15:11:15 -0500 Subject: [PATCH] Add composable index template support putIndexTemplate(), getIndexTemplate(), indexTemplateExists() and deleteIndexTemplate() on Stretch and ClientContract. An index created later whose name matches a template's index_patterns, including one Elasticsearch auto-creates on a bulk write, gets the template's settings, mappings and aliases. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 4 + .../Connection/Contracts/ClientContract.php | 44 ++++++++++ .../Services/ElasticsearchClient.php | 86 +++++++++++++++++++ src/Facades/Stretch.php | 4 + src/Stretch.php | 66 ++++++++++++++ tests/Feature/StretchTest.php | 29 +++++++ 6 files changed, 233 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index d32af67..bd60dd3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,10 @@ All notable changes to `refactor-circus/stretch` are documented in this file. ## [Unreleased](https://github.com/Refactor-Circus/Stretch/commits/main) +### Added + +- Composable index templates: `putIndexTemplate()`, `getIndexTemplate()`, `indexTemplateExists()` and `deleteIndexTemplate()` on `Stretch` (and `ClientContract`). An index created later whose name matches a template's `index_patterns`, including one Elasticsearch auto-creates on a bulk write, gets the template's settings, mappings and aliases. + ### Breaking - Moved to the Refactor Circus organisation: the package is now `refactor-circus/stretch` with the PHP namespace `RefactorCircus\Stretch` (it was `jayi/stretch` and `JayI\Stretch`). Update `composer.json` requirements and `use` statements. Old class names are not kept as aliases, so stored values written under them - polymorphic `*_type` columns, audit subjects, Pennant feature names - need updating to the new names. diff --git a/src/Domains/Connection/Contracts/ClientContract.php b/src/Domains/Connection/Contracts/ClientContract.php index 9109cd3..554db49 100644 --- a/src/Domains/Connection/Contracts/ClientContract.php +++ b/src/Domains/Connection/Contracts/ClientContract.php @@ -322,6 +322,50 @@ public function getSynonymRule(string $setId, string $ruleId): array; */ public function deleteSynonymRule(string $setId, string $ruleId, array $options = []): array; + // ── Index Templates ───────────────────────────────────── + + /** + * Create or replace a composable index template. + * + * @param string $name The template name + * @param array $body The template definition (index_patterns, template, priority, etc.) + * @return array The response + * + * @throws StretchException If the operation fails + */ + public function putIndexTemplate(string $name, array $body): array; + + /** + * Get a composable index template by name. + * + * @param string $name The template name + * @return array The response (`index_templates` list) + * + * @throws StretchException If the operation fails + */ + public function getIndexTemplate(string $name): array; + + /** + * Check whether a composable index template exists. + * + * @param string $name The template name + * @return bool True if the template exists + * + * @throws StretchException If the check fails for a reason other than a 404 + */ + public function indexTemplateExists(string $name): bool; + + /** + * Delete a composable index template. Indices it already created keep + * their settings and mappings. + * + * @param string $name The template name + * @return array The response + * + * @throws StretchException If the operation fails + */ + public function deleteIndexTemplate(string $name): array; + // ── Ingest Pipelines ──────────────────────────────────── /** diff --git a/src/Domains/Connection/Services/ElasticsearchClient.php b/src/Domains/Connection/Services/ElasticsearchClient.php index 52a08ad..ae7f5bb 100644 --- a/src/Domains/Connection/Services/ElasticsearchClient.php +++ b/src/Domains/Connection/Services/ElasticsearchClient.php @@ -606,6 +606,92 @@ public function deleteSynonymRule(string $setId, string $ruleId, array $options // ── Ingest Pipelines ──────────────────────────────────── + /** + * Create or replace a composable index template. + * + * @param string $name The template name + * @param array $body The template definition + * @return array The response + * + * @throws StretchException If the operation fails + */ + public function putIndexTemplate(string $name, array $body): array + { + try { + return $this->client->indices()->putIndexTemplate([ + 'name' => $name, + 'body' => $body, + ])->asArray(); + } catch (Exception $exception) { + throw new StretchException("Failed to put index template '$name': {$exception->getMessage()}", (int) $exception->getCode(), $exception); + } + } + + /** + * Get a composable index template by name. + * + * @param string $name The template name + * @return array The response + * + * @throws StretchException If the operation fails + */ + public function getIndexTemplate(string $name): array + { + try { + return $this->client->indices()->getIndexTemplate(['name' => $name])->asArray(); + } catch (Exception $exception) { + throw new StretchException("Failed to get index template '$name': {$exception->getMessage()}", (int) $exception->getCode(), $exception); + } + } + + /** + * Check whether a composable index template exists. + * + * @param string $name The template name + * @return bool True if the template exists + * + * @throws StretchException If the check fails for a reason other than a 404 + */ + public function indexTemplateExists(string $name): bool + { + try { + return $this->performIndexTemplateExists($name); + } catch (ClientResponseException $exception) { + if ($exception->getCode() === 404) { + return false; + } + + throw new StretchException("Failed to check index template '$name': {$exception->getMessage()}", (int) $exception->getCode(), $exception); + } catch (Exception $exception) { + throw new StretchException("Failed to check index template '$name': {$exception->getMessage()}", (int) $exception->getCode(), $exception); + } + } + + /** + * Perform the template-exists request. Split out so tests can stub it. + */ + protected function performIndexTemplateExists(string $name): bool + { + return $this->client->indices()->existsIndexTemplate(['name' => $name])->asBool(); + } + + /** + * Delete a composable index template. + * + * @param string $name The template name + * @return array The response + * + * @throws StretchException If the operation fails + */ + public function deleteIndexTemplate(string $name): array + { + try { + return $this->client->indices()->deleteIndexTemplate(['name' => $name])->asArray(); + } catch (Exception $exception) { + throw new StretchException("Failed to delete index template '$name': {$exception->getMessage()}", (int) $exception->getCode(), $exception); + } + } + /** * Create or update an ingest pipeline. * diff --git a/src/Facades/Stretch.php b/src/Facades/Stretch.php index 5626d5a..6e34cd9 100644 --- a/src/Facades/Stretch.php +++ b/src/Facades/Stretch.php @@ -46,6 +46,10 @@ * @method static array putSynonymRule(string $setId, string $ruleId, array $rule, array $options = []) Create or update a synonym rule * @method static array getSynonymRule(string $setId, string $ruleId) Get a synonym rule * @method static array deleteSynonymRule(string $setId, string $ruleId, array $options = []) Delete a synonym rule + * @method static array putIndexTemplate(string $name, array $body) Create or replace a composable index template + * @method static array getIndexTemplate(string $name) Get a composable index template + * @method static bool indexTemplateExists(string $name) Check whether a composable index template exists + * @method static array deleteIndexTemplate(string $name) Delete a composable index template * @method static array putPipeline(string $id, array $body) Create or update an ingest pipeline * @method static array getPipeline(string $id) Get an ingest pipeline by ID * @method static array deletePipeline(string $id) Delete an ingest pipeline diff --git a/src/Stretch.php b/src/Stretch.php index 17a087f..68ffcc9 100644 --- a/src/Stretch.php +++ b/src/Stretch.php @@ -634,6 +634,72 @@ public function deleteSynonymRule(string $setId, string $ruleId, array $options // ── Ingest Pipelines ──────────────────────────────────── + /** + * Create or replace a composable index template. Indices created later + * whose names match its `index_patterns` (including ones Elasticsearch + * auto-creates on a bulk write) get its settings, mappings and aliases. + * + * @param string $name The template name + * @param array $body The template definition + * @return array The Elasticsearch response + * + * @throws StretchException If the operation fails + * + * @example + * ```php + * Stretch::putIndexTemplate('orders', [ + * 'index_patterns' => ['orders-*'], + * 'template' => [ + * 'settings' => ['number_of_shards' => 1], + * 'mappings' => ['dynamic' => 'strict', 'properties' => [...]], + * 'aliases' => ['orders_search' => new \stdClass], + * ], + * ]); + * ``` + */ + public function putIndexTemplate(string $name, array $body): array + { + return $this->client->putIndexTemplate($name, $body); + } + + /** + * Get a composable index template by name. + * + * @param string $name The template name + * @return array The Elasticsearch response (`index_templates` list) + * + * @throws StretchException If the operation fails + */ + public function getIndexTemplate(string $name): array + { + return $this->client->getIndexTemplate($name); + } + + /** + * Check whether a composable index template exists. + * + * @param string $name The template name + * @return bool True if the template exists + */ + public function indexTemplateExists(string $name): bool + { + return $this->client->indexTemplateExists($name); + } + + /** + * Delete a composable index template. Indices it already created keep + * their settings and mappings. + * + * @param string $name The template name + * @return array The Elasticsearch response + * + * @throws StretchException If the operation fails + */ + public function deleteIndexTemplate(string $name): array + { + return $this->client->deleteIndexTemplate($name); + } + /** * Create or update an ingest pipeline. * diff --git a/tests/Feature/StretchTest.php b/tests/Feature/StretchTest.php index 762c096..c4d75f4 100644 --- a/tests/Feature/StretchTest.php +++ b/tests/Feature/StretchTest.php @@ -168,3 +168,32 @@ expect($result['deleted'])->toBe(100); }); + +it('puts an index template', function () { + $body = ['index_patterns' => ['orders-*'], 'template' => ['mappings' => ['dynamic' => 'strict']]]; + $mockClient = m::mock(ClientContract::class); + $mockClient->shouldReceive('putIndexTemplate')->with('orders', $body)->once()->andReturn(['acknowledged' => true]); + + expect((new Stretch($mockClient))->putIndexTemplate('orders', $body))->toBe(['acknowledged' => true]); +}); + +it('gets an index template', function () { + $mockClient = m::mock(ClientContract::class); + $mockClient->shouldReceive('getIndexTemplate')->with('orders')->once()->andReturn(['index_templates' => [['name' => 'orders']]]); + + expect((new Stretch($mockClient))->getIndexTemplate('orders')['index_templates'][0]['name'])->toBe('orders'); +}); + +it('checks whether an index template exists', function () { + $mockClient = m::mock(ClientContract::class); + $mockClient->shouldReceive('indexTemplateExists')->with('orders')->once()->andReturn(false); + + expect((new Stretch($mockClient))->indexTemplateExists('orders'))->toBeFalse(); +}); + +it('deletes an index template', function () { + $mockClient = m::mock(ClientContract::class); + $mockClient->shouldReceive('deleteIndexTemplate')->with('orders')->once()->andReturn(['acknowledged' => true]); + + expect((new Stretch($mockClient))->deleteIndexTemplate('orders'))->toBe(['acknowledged' => true]); +});