feat(query): add shape query

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

Author: Spamercz

doc/02-query-objects.md

@@ -441,6 +441,20 @@ new \Spameri\ElasticQuery\Query\GeoDistance(
 );
 ```
 
+##### Shape Query
+Same as `geo_shape` but for Cartesian `shape` fields (non-geographic plane).
+- Class: `\Spameri\ElasticQuery\Query\Shape`
+- [Documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-shape-query.html)
+- [Implementation](https://github.com/Spameri/ElasticQuery/blob/master/src/Query/Shape.php)
+
+```php
+new \Spameri\ElasticQuery\Query\Shape(
+	field: 'geometry',
+	shape: ['type' => 'envelope', 'coordinates' => [[0, 100], [100, 0]]],
+	relation: 'intersects',
+);
+```
+
 ##### GeoShape Query
 Match `geo_shape`-indexed documents against an arbitrary geometry.
 - Class: `\Spameri\ElasticQuery\Query\GeoShape`

src/Query/Shape.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace Spameri\ElasticQuery\Query;
+
+/**
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-shape-query.html
+ */
+class Shape implements \Spameri\ElasticQuery\Query\LeafQueryInterface
+{
+
+	/**
+	 * @param array<string, mixed> $shape
+	 */
+	public function __construct(
+		private string $field,
+		private array $shape,
+		private string $relation = 'intersects',
+		private bool|null $ignoreUnmapped = null,
+	)
+	{
+		if ( ! \in_array($relation, ['intersects', 'disjoint', 'within', 'contains'], true)) {
+			throw new \Spameri\ElasticQuery\Exception\InvalidArgumentException(
+				'Shape relation must be one of: intersects, disjoint, within, contains.',
+			);
+		}
+	}
+
+
+	public function key(): string
+	{
+		return 'shape_' . $this->field;
+	}
+
+
+	/**
+	 * @return array<string, array<string, array<string, mixed>>>
+	 */
+	public function toArray(): array
+	{
+		$inner = [
+			'shape' => $this->shape,
+			'relation' => $this->relation,
+		];
+
+		if ($this->ignoreUnmapped !== null) {
+			$inner['ignore_unmapped'] = $this->ignoreUnmapped;
+		}
+
+		return [
+			'shape' => [
+				$this->field => $inner,
+			],
+		];
+	}
+
+}

tests/SpameriTests/ElasticQuery/Query/Shape.phpt

@@ -0,0 +1,61 @@
+<?php declare(strict_types = 1);
+
+namespace SpameriTests\ElasticQuery\Query;
+
+require_once __DIR__ . '/../../bootstrap.php';
+
+
+class Shape extends \Tester\TestCase
+{
+
+	private const INDEX = 'spameri_test_query_shape';
+
+
+	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
+	{
+		$shape = new \Spameri\ElasticQuery\Query\Shape(
+			field: 'geometry',
+			shape: ['type' => 'envelope', 'coordinates' => [[0, 100], [100, 0]]],
+			relation: 'intersects',
+		);
+
+		$array = $shape->toArray();
+
+		\Tester\Assert::same('envelope', $array['shape']['geometry']['shape']['type']);
+	}
+
+
+	public function testKey(): void
+	{
+		$shape = new \Spameri\ElasticQuery\Query\Shape('geometry', ['type' => 'point', 'coordinates' => [0, 0]]);
+
+		\Tester\Assert::same('shape_geometry', $shape->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 Shape())->run();