feat(query): add span not query

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

Author: Spamercz

doc/02-query-objects.md

@@ -642,6 +642,21 @@ $span = new \Spameri\ElasticQuery\Query\SpanOr(
 $span->addClause(new \Spameri\ElasticQuery\Query\SpanTerm('field', 'value2'));
 ```
 
+##### SpanNot Query
+Match `include` spans not overlapping `exclude` spans.
+- Class: `\Spameri\ElasticQuery\Query\SpanNot`
+- [Documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-span-not-query.html)
+- [Implementation](https://github.com/Spameri/ElasticQuery/blob/master/src/Query/SpanNot.php)
+
+```php
+new \Spameri\ElasticQuery\Query\SpanNot(
+	include: new \Spameri\ElasticQuery\Query\SpanTerm('field', 'hot'),
+	exclude: new \Spameri\ElasticQuery\Query\SpanTerm('field', 'dog'),
+	pre: 0,
+	post: 1,
+);
+```
+
 ##### SpanTerm Query
 Match a single term in a span-aware way.
 - Class: `\Spameri\ElasticQuery\Query\SpanTerm`

src/Query/SpanNot.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace Spameri\ElasticQuery\Query;
+
+/**
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-span-not-query.html
+ */
+class SpanNot implements \Spameri\ElasticQuery\Query\LeafQueryInterface
+{
+
+	public function __construct(
+		private \Spameri\ElasticQuery\Query\LeafQueryInterface $include,
+		private \Spameri\ElasticQuery\Query\LeafQueryInterface $exclude,
+		private int|null $pre = null,
+		private int|null $post = null,
+		private int|null $dist = null,
+	)
+	{
+	}
+
+
+	public function key(): string
+	{
+		return 'span_not_' . $this->include->key() . '_' . $this->exclude->key();
+	}
+
+
+	/**
+	 * @return array<string, array<string, mixed>>
+	 */
+	public function toArray(): array
+	{
+		$body = [
+			'include' => $this->include->toArray(),
+			'exclude' => $this->exclude->toArray(),
+		];
+
+		if ($this->pre !== null) {
+			$body['pre'] = $this->pre;
+		}
+
+		if ($this->post !== null) {
+			$body['post'] = $this->post;
+		}
+
+		if ($this->dist !== null) {
+			$body['dist'] = $this->dist;
+		}
+
+		return [
+			'span_not' => $body,
+		];
+	}
+
+}

tests/SpameriTests/ElasticQuery/Query/SpanNot.phpt

@@ -0,0 +1,68 @@
+<?php declare(strict_types = 1);
+
+namespace SpameriTests\ElasticQuery\Query;
+
+require_once __DIR__ . '/../../bootstrap.php';
+
+
+class SpanNot extends \Tester\TestCase
+{
+
+	private const INDEX = 'spameri_test_query_span_not';
+
+
+	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\SpanNot(
+			include: new \Spameri\ElasticQuery\Query\SpanTerm('field', 'hot'),
+			exclude: new \Spameri\ElasticQuery\Query\SpanTerm('field', 'dog'),
+			pre: 0,
+			post: 1,
+		);
+
+		$array = $span->toArray();
+
+		\Tester\Assert::same(0, $array['span_not']['pre']);
+		\Tester\Assert::same(1, $array['span_not']['post']);
+		\Tester\Assert::true(isset($array['span_not']['include']));
+		\Tester\Assert::true(isset($array['span_not']['exclude']));
+	}
+
+
+	public function testKey(): void
+	{
+		$span = new \Spameri\ElasticQuery\Query\SpanNot(
+			new \Spameri\ElasticQuery\Query\SpanTerm('field', 'hot'),
+			new \Spameri\ElasticQuery\Query\SpanTerm('field', 'dog'),
+		);
+
+		\Tester\Assert::same('span_not_span_term_field_hot_span_term_field_dog', $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 SpanNot())->run();