feat: add distance value object and ci workflows

server/src/Service/PointProximityValidator.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace App\Service;
 
+use App\ValueObject\Distance;
 use App\ValueObject\Point;
 use App\Exception\PointTooFarException;
 use Psr\Log\LoggerInterface;
@@ -21,7 +22,7 @@ final class PointProximityValidator
 
     public function assertWithinRange(Point $userLocation, Point $signalLocation): void
     {
-        $distance = $this->distanceInKm($userLocation, $signalLocation);
+        $distance = Distance::betweenPoints($userLocation, $signalLocation)->inKilometers();
 
         $this->logger->debug('Calculated proximity between user and signal.', [
             'distance_km' => $distance,
@@ -36,17 +37,4 @@ final class PointProximityValidator
             throw new PointTooFarException($this->maximumDistanceKm);
         }
     }
-
-    private function distanceInKm(Point $a, Point $b): float
-    {
-        $lat1 = deg2rad($a->getLat());
-        $lat2 = deg2rad($b->getLat());
-        $deltaLat = deg2rad($b->getLat() - $a->getLat());
-        $deltaLng = deg2rad($b->getLng() - $a->getLng());
-
-        $haversine = sin($deltaLat / 2) ** 2 + cos($lat1) * cos($lat2) * sin($deltaLng / 2) ** 2;
-        $c = 2 * atan2(sqrt($haversine), sqrt(1 - $haversine));
-
-        return 6371 * $c;
-    }
 }

server/src/ValueObject/Distance.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\ValueObject;
+
+final class Distance
+{
+    private const EARTH_RADIUS_KM = 6371;
+
+    private function __construct(
+        private readonly float $kilometers,
+    ) {
+    }
+
+    public static function betweenPoints(Point $from, Point $to): self
+    {
+        $lat1 = deg2rad($from->getLat());
+        $lat2 = deg2rad($to->getLat());
+        $deltaLat = deg2rad($to->getLat() - $from->getLat());
+        $deltaLng = deg2rad($to->getLng() - $from->getLng());
+
+        $haversine = sin($deltaLat / 2) ** 2 + cos($lat1) * cos($lat2) * sin($deltaLng / 2) ** 2;
+        $centralAngle = 2 * atan2(sqrt($haversine), sqrt(1 - $haversine));
+
+        return new self(self::EARTH_RADIUS_KM * $centralAngle);
+    }
+
+    public function inKilometers(): float
+    {
+        return $this->kilometers;
+    }
+
+    public function inMeters(): float
+    {
+        return $this->kilometers * 1000;
+    }
+}

server/tests/Unit/ValueObject/DistanceTest.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\ValueObject;
+
+use App\ValueObject\Distance;
+use App\ValueObject\Point;
+use PHPUnit\Framework\TestCase;
+
+final class DistanceTest extends TestCase
+{
+    public function testCalculatesDistanceBetweenTwoPointsInKilometers(): void
+    {
+        $origin = Point::fromLatLng(48.8566, 2.3522); // Paris
+        $destination = Point::fromLatLng(51.5074, -0.1278); // London
+
+        $distance = Distance::betweenPoints($origin, $destination);
+
+        self::assertEqualsWithDelta(343.4, $distance->inKilometers(), 0.5);
+    }
+
+    public function testCanConvertDistanceToMeters(): void
+    {
+        $origin = Point::fromLatLng(0.0, 0.0);
+        $destination = Point::fromLatLng(0.0, 0.009); // ~1km east on equator
+
+        $distance = Distance::betweenPoints($origin, $destination);
+
+        self::assertEqualsWithDelta(1000, $distance->inMeters(), 10);
+    }
+}