feat(query): add percolate query

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

Author: Spamercz

doc/02-query-objects.md

@@ -559,6 +559,19 @@ new \Spameri\ElasticQuery\Query\Pinned(
 );
 ```
 
+##### Percolate Query
+Match a document against stored queries (reverse search).
+- Class: `\Spameri\ElasticQuery\Query\Percolate`
+- [Documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-percolate-query.html)
+- [Implementation](https://github.com/Spameri/ElasticQuery/blob/master/src/Query/Percolate.php)
+
+```php
+new \Spameri\ElasticQuery\Query\Percolate(
+	field: 'query',
+	document: ['message' => 'A new bonsai tree'],
+);
+```
+
 ##### Script Query
 Filter documents with a Painless boolean script.
 - Class: `\Spameri\ElasticQuery\Query\Script`

src/Query/Percolate.php

@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace Spameri\ElasticQuery\Query;
+
+/**
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-percolate-query.html
+ */
+class Percolate implements \Spameri\ElasticQuery\Query\LeafQueryInterface
+{
+
+	/**
+	 * @param array<string, mixed>|null $document Inline document to percolate.
+	 */
+	public function __construct(
+		private string $field,
+		private array|null $document = null,
+		private string|null $index = null,
+		private string|null $id = null,
+	)
+	{
+		if ($document === null && ($index === null || $id === null)) {
+			throw new \Spameri\ElasticQuery\Exception\InvalidArgumentException(
+				'Percolate query requires either a document, or both index and id.',
+			);
+		}
+	}
+
+
+	public function key(): string
+	{
+		return 'percolate_' . $this->field;
+	}
+
+
+	/**
+	 * @return array<string, array<string, mixed>>
+	 */
+	public function toArray(): array
+	{
+		$body = [
+			'field' => $this->field,
+		];
+
+		if ($this->document !== null) {
+			$body['document'] = $this->document;
+
+		} else {
+			$body['index'] = $this->index;
+			$body['id'] = $this->id;
+		}
+
+		return [
+			'percolate' => $body,
+		];
+	}
+
+}

tests/SpameriTests/ElasticQuery/Query/Percolate.phpt

@@ -0,0 +1,89 @@
+<?php declare(strict_types = 1);
+
+namespace SpameriTests\ElasticQuery\Query;
+
+require_once __DIR__ . '/../../bootstrap.php';
+
+
+class Percolate extends \Tester\TestCase
+{
+
+	private const INDEX = 'spameri_test_query_percolate';
+
+
+	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 testToArrayInline(): void
+	{
+		$percolate = new \Spameri\ElasticQuery\Query\Percolate(
+			field: 'query',
+			document: ['message' => 'A new bonsai tree'],
+		);
+
+		$array = $percolate->toArray();
+
+		\Tester\Assert::same(['message' => 'A new bonsai tree'], $array['percolate']['document']);
+	}
+
+
+	public function testToArrayById(): void
+	{
+		$percolate = new \Spameri\ElasticQuery\Query\Percolate(
+			field: 'query',
+			index: 'my-index',
+			id: '1',
+		);
+
+		$array = $percolate->toArray();
+
+		\Tester\Assert::same('my-index', $array['percolate']['index']);
+		\Tester\Assert::same('1', $array['percolate']['id']);
+	}
+
+
+	public function testRequiresDocOrId(): void
+	{
+		\Tester\Assert::exception(
+			static function (): void {
+				new \Spameri\ElasticQuery\Query\Percolate(field: 'query');
+			},
+			\Spameri\ElasticQuery\Exception\InvalidArgumentException::class,
+		);
+	}
+
+
+	public function testKey(): void
+	{
+		$percolate = new \Spameri\ElasticQuery\Query\Percolate(
+			field: 'query',
+			document: ['m' => 'hello'],
+		);
+
+		\Tester\Assert::same('percolate_query', $percolate->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 Percolate())->run();