Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
94.12%
16 / 17
100.00%
3 / 3
 CRAP
100.00%
1 / 1
GeoPoint
100.00%
16 / 16
100.00%
3 / 3
 7
100.00%
1 / 1
 __construct
100.00%
8 / 8
100.00%
1 / 1
 5
 getCoordinatesFormatted
100.00%
1 / 1
100.00%
1 / 1
 1
 toArray
100.00%
7 / 7
100.00%
1 / 1
 1
1<?php
2
3declare(strict_types=1);
4
5/** @license For full copyright and license information, please see the LICENSE.md file. */
6
7namespace App\Modules\Map\Domain\Model;
8
9defined('AMMONLY_APP') || exit('Direct script access is forbidden.');
10
11use InvalidArgumentException;
12
13/**
14 * GeoPoint Value Object.
15 *
16 * Encapsulates geographic latitude, longitude, human-readable label, and contextual metadata.
17 *
18 * @package App\Modules\Map\Domain\Model
19 */
20final readonly class GeoPoint
21{
22    /**
23     * GeoPoint constructor.
24     *
25     * @param float                $latitude  WGS-84 latitude in degrees (-90.0 to +90.0).
26     * @param float                $longitude WGS-84 longitude in degrees (-180.0 to +180.0).
27     * @param string               $label     Display label or title.
28     * @param string               $address   Resolved address string.
29     * @param array<string, mixed> $metadata  Arbitrary entity metadata (e.g. record_id, module).
30     *
31     * @throws InvalidArgumentException When coordinates are outside valid ranges.
32     */
33    public function __construct(
34        public float $latitude,
35        public float $longitude,
36        public string $label = '',
37        public string $address = '',
38        public array $metadata = []
39    ) {
40        if ($latitude < -90.0 || $latitude > 90.0) {
41            throw new InvalidArgumentException(
42                sprintf('Latitude %.6f out of bounds [-90.0, 90.0].', $latitude)
43            );
44        }
45
46        if ($longitude < -180.0 || $longitude > 180.0) {
47            throw new InvalidArgumentException(
48                sprintf('Longitude %.6f out of bounds [-180.0, 180.0].', $longitude)
49            );
50        }
51    }
52
53    /**
54     * Formats coordinates into standard "lat, lon" string with 6 decimals.
55     */
56    public function getCoordinatesFormatted(): string
57    {
58        return sprintf('%.6f, %.6f', $this->latitude, $this->longitude);
59    }
60
61    /**
62     * Serializes value object into associative array representation.
63     *
64     * @return array{
65     *     latitude: float,
66     *     longitude: float,
67     *     label: string,
68     *     address: string,
69     *     metadata: array<string, mixed>
70     * }
71     */
72    public function toArray(): array
73    {
74        return [
75            'latitude'  => $this->latitude,
76            'longitude' => $this->longitude,
77            'label'     => $this->label,
78            'address'   => $this->address,
79            'metadata'  => $this->metadata,
80        ];
81    }
82}