feat(query): add span term query

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Spamercz

doc/02-query-objects.md

@@ -597,6 +597,22 @@ new \Spameri\ElasticQuery\Query\Script(
 
 ---
 
+## Span Queries
+
+Positional matching — useful for term-position-aware searches. Span clauses can be composed via the `*_near`, `*_or`, etc. queries.
+
+##### SpanTerm Query
+Match a single term in a span-aware way.
+- Class: `\Spameri\ElasticQuery\Query\SpanTerm`
+- [Documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-span-term-query.html)
+- [Implementation](https://github.com/Spameri/ElasticQuery/blob/master/src/Query/SpanTerm.php)
+
+```php
+new \Spameri\ElasticQuery\Query\SpanTerm(field: 'text', query: 'quick');
+```
+
+---
+
 ## Boolean Query Collections
 
 These collections implement `LeafQueryInterface` and can be nested arbitrarily.

src/Query/SpanTerm.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace Spameri\ElasticQuery\Query;
+
+/**
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-span-term-query.html
+ */
+class SpanTerm implements \Spameri\ElasticQuery\Query\LeafQueryInterface
+{
+
+	public function __construct(
+		private string $field,
+		private string $query,
+		private float $boost = 1.0,
+	)
+	{
+	}
+
+
+	public function key(): string
+	{
+		return 'span_term_' . $this->field . '_' . $this->query;
+	}
+
+
+	/**
+	 * @return array<string, array<string, array<string, mixed>>>
+	 */
+	public function toArray(): array
+	{
+		return [
+			'span_term' => [
+				$this->field => [
+					'value' => $this->query,
+					'boost' => $this->boost,
+				],
+			],
+		];
+	}
+
+}

tests/SpameriTests/ElasticQuery/Query/SpanTerm.phpt

@@ -0,0 +1,57 @@
+<?php declare(strict_types = 1);
+
+namespace SpameriTests\ElasticQuery\Query;
+
+require_once __DIR__ . '/../../bootstrap.php';
+
+
+class SpanTerm extends \Tester\TestCase
+{
+
+	private const INDEX = 'spameri_test_query_span_term';
+
+
+	public function setUp(): void
+	{
+		$ch = \curl_init();
+		\curl_setopt($ch, \CURLOPT_URL, \ELASTICSEARCH_HOST . '/' . self::INDEX);
+		\curl_setopt($ch, \CURLOPT_RETURNTRANSFER, 1);
+		\curl_setopt($ch, \CURLOPT_CUSTOMREQUEST, 'PUT');
+		\curl_setopt($ch, \CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
+
+		\curl_exec($ch);
+	}
+
+
+	public function testToArray(): void
+	{
+		$span = new \Spameri\ElasticQuery\Query\SpanTerm('text', 'quick');
+
+		$array = $span->toArray();
+
+		\Tester\Assert::same('quick', $array['span_term']['text']['value']);
+	}
+
+
+	public function testKey(): void
+	{
+		$span = new \Spameri\ElasticQuery\Query\SpanTerm('text', 'quick');
+
+		\Tester\Assert::same('span_term_text_quick', $span->key());
+	}
+
+
+	public function tearDown(): void
+	{
+		$ch = \curl_init();
+		\curl_setopt($ch, \CURLOPT_URL, \ELASTICSEARCH_HOST . '/' . self::INDEX);
+		\curl_setopt($ch, \CURLOPT_RETURNTRANSFER, 1);
+		\curl_setopt($ch, \CURLOPT_CUSTOMREQUEST, 'DELETE');
+		\curl_setopt($ch, \CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
+
+		\curl_exec($ch);
+	}
+
+}
+
+(new SpanTerm())->run();