feat(query): add geo shape query

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

Author: Spamercz

doc/02-query-objects.md

@@ -441,6 +441,23 @@ new \Spameri\ElasticQuery\Query\GeoDistance(
 );
 ```
 
+##### GeoShape Query
+Match `geo_shape`-indexed documents against an arbitrary geometry.
+- Class: `\Spameri\ElasticQuery\Query\GeoShape`
+- [Documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-geo-shape-query.html)
+- [Implementation](https://github.com/Spameri/ElasticQuery/blob/master/src/Query/GeoShape.php)
+
+```php
+new \Spameri\ElasticQuery\Query\GeoShape(
+	field: 'location',
+	shape: [
+		'type' => 'envelope',
+		'coordinates' => [[13.0, 53.0], [14.0, 52.0]],
+	],
+	relation: 'within', // intersects | disjoint | within | contains
+);
+```
+
 ##### GeoBoundingBox Query
 Match documents whose geo_point falls inside a top-left/bottom-right rectangle.
 - Class: `\Spameri\ElasticQuery\Query\GeoBoundingBox`

src/Query/GeoShape.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-geo-shape-query.html
+ */
+class GeoShape implements \Spameri\ElasticQuery\Query\LeafQueryInterface
+{
+
+	/**
+	 * @param array<string, mixed> $shape GeoJSON-style shape, e.g.
+	 *                                    ['type' => 'envelope', 'coordinates' => [[13, 53], [14, 52]]].
+	 */
+	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(
+				'GeoShape relation must be one of: intersects, disjoint, within, contains.',
+			);
+		}
+	}
+
+
+	public function key(): string
+	{
+		return 'geo_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 [
+			'geo_shape' => [
+				$this->field => $inner,
+			],
+		];
+	}
+
+}

tests/SpameriTests/ElasticQuery/Query/GeoShape.phpt

@@ -0,0 +1,76 @@
+<?php declare(strict_types = 1);
+
+namespace SpameriTests\ElasticQuery\Query;
+
+require_once __DIR__ . '/../../bootstrap.php';
+
+
+class GeoShape extends \Tester\TestCase
+{
+
+	private const INDEX = 'spameri_test_query_geo_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
+	{
+		$geoShape = new \Spameri\ElasticQuery\Query\GeoShape(
+			field: 'location',
+			shape: [
+				'type' => 'envelope',
+				'coordinates' => [[13.0, 53.0], [14.0, 52.0]],
+			],
+			relation: 'within',
+		);
+
+		$array = $geoShape->toArray();
+
+		\Tester\Assert::same('envelope', $array['geo_shape']['location']['shape']['type']);
+		\Tester\Assert::same('within', $array['geo_shape']['location']['relation']);
+	}
+
+
+	public function testRelationValidated(): void
+	{
+		\Tester\Assert::exception(
+			static function (): void {
+				new \Spameri\ElasticQuery\Query\GeoShape('loc', ['type' => 'point', 'coordinates' => [0, 0]], 'nonsense');
+			},
+			\Spameri\ElasticQuery\Exception\InvalidArgumentException::class,
+		);
+	}
+
+
+	public function testKey(): void
+	{
+		$geoShape = new \Spameri\ElasticQuery\Query\GeoShape('location', ['type' => 'point', 'coordinates' => [0, 0]]);
+
+		\Tester\Assert::same('geo_shape_location', $geoShape->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 GeoShape())->run();