feat(query): add distance feature query

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

Author: Spamercz

doc/02-query-objects.md

@@ -532,6 +532,20 @@ new \Spameri\ElasticQuery\Query\RankFeature(
 );
 ```
 
+##### DistanceFeature Query
+Boost documents whose date or geo_point is close to an origin.
+- Class: `\Spameri\ElasticQuery\Query\DistanceFeature`
+- [Documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-distance-feature-query.html)
+- [Implementation](https://github.com/Spameri/ElasticQuery/blob/master/src/Query/DistanceFeature.php)
+
+```php
+new \Spameri\ElasticQuery\Query\DistanceFeature(
+	field: 'production_date',
+	origin: 'now',
+	pivot: '7d',
+);
+```
+
 ##### Script Query
 Filter documents with a Painless boolean script.
 - Class: `\Spameri\ElasticQuery\Query\Script`

src/Query/DistanceFeature.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace Spameri\ElasticQuery\Query;
+
+/**
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-distance-feature-query.html
+ */
+class DistanceFeature implements \Spameri\ElasticQuery\Query\LeafQueryInterface
+{
+
+	/**
+	 * @param array<int, float>|string $origin Either [lat, lon] for geo_point or a date string for date.
+	 */
+	public function __construct(
+		private string $field,
+		private array|string $origin,
+		private string $pivot,
+		private float $boost = 1.0,
+	)
+	{
+	}
+
+
+	public function key(): string
+	{
+		return 'distance_feature_' . $this->field;
+	}
+
+
+	/**
+	 * @return array<string, array<string, mixed>>
+	 */
+	public function toArray(): array
+	{
+		return [
+			'distance_feature' => [
+				'field' => $this->field,
+				'origin' => $this->origin,
+				'pivot' => $this->pivot,
+				'boost' => $this->boost,
+			],
+		];
+	}
+
+}

tests/SpameriTests/ElasticQuery/Query/DistanceFeature.phpt

@@ -0,0 +1,76 @@
+<?php declare(strict_types = 1);
+
+namespace SpameriTests\ElasticQuery\Query;
+
+require_once __DIR__ . '/../../bootstrap.php';
+
+
+class DistanceFeature extends \Tester\TestCase
+{
+
+	private const INDEX = 'spameri_test_query_distance_feature';
+
+
+	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 testToArrayDate(): void
+	{
+		$df = new \Spameri\ElasticQuery\Query\DistanceFeature(
+			field: 'production_date',
+			origin: 'now',
+			pivot: '7d',
+		);
+
+		$array = $df->toArray();
+
+		\Tester\Assert::same('now', $array['distance_feature']['origin']);
+		\Tester\Assert::same('7d', $array['distance_feature']['pivot']);
+	}
+
+
+	public function testToArrayGeo(): void
+	{
+		$df = new \Spameri\ElasticQuery\Query\DistanceFeature(
+			field: 'location',
+			origin: [50.0, 14.4],
+			pivot: '1000m',
+		);
+
+		$array = $df->toArray();
+
+		\Tester\Assert::same([50.0, 14.4], $array['distance_feature']['origin']);
+	}
+
+
+	public function testKey(): void
+	{
+		$df = new \Spameri\ElasticQuery\Query\DistanceFeature('location', [0, 0], '1km');
+
+		\Tester\Assert::same('distance_feature_location', $df->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 DistanceFeature())->run();