Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00%
0 / 1
n/a
0 / 0
 CRAP
n/a
0 / 0
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\Repository;
8
9defined('AMMONLY_APP') || exit('Direct script access is forbidden.');
10
11use App\Modules\Map\Domain\Model\GeoPoint;
12use App\Modules\Map\Domain\Model\RouteResultDto;
13
14/**
15 * Map API Client Interface.
16 *
17 * Contract for interacting with the Ammonly Maps Engine (tiles, geocoding, reverse geocoding, routing).
18 *
19 * @package App\Modules\Map\Domain\Repository
20 */
21interface MapApiClientInterface
22{
23    /**
24     * Geocodes an address or query string into matching GeoPoint candidates.
25     *
26     * @param string $query Address search query (e.g. "New York Broadway 1").
27     * @param int    $limit Maximum candidate count.
28     * @return array<int, GeoPoint> Found points ordered by relevance.
29     */
30    public function geocode(string $query, int $limit = 5): array;
31
32    /**
33     * Reverse geocodes coordinates into an address GeoPoint.
34     *
35     * @param float $latitude  WGS-84 latitude.
36     * @param float $longitude WGS-84 longitude.
37     * @return GeoPoint|null Resolved point with address metadata or null on failure.
38     */
39    public function reverseGeocode(float $latitude, float $longitude): ?GeoPoint;
40
41    /**
42     * Calculates driving route between origin and destination points.
43     *
44     * @param GeoPoint $origin      Start coordinate point.
45     * @param GeoPoint $destination End coordinate point.
46     * @return RouteResultDto|null Calculated route or null when no path exists.
47     */
48    public function calculateRoute(GeoPoint $origin, GeoPoint $destination): ?RouteResultDto;
49
50    /**
51     * Returns tile URL template with injected API key.
52     *
53     * @return string URL template (e.g. "https://map.ammonly.com/tile/{z}/{x}/{y}.png?key=...").
54     */
55    public function getTileUrlTemplate(): string;
56
57    /**
58     * Returns native Dark Mode tile URL template with injected API key.
59     *
60     * @return string URL template (e.g. "https://map.ammonly.com/tile-dark/{z}/{x}/{y}.png?key=...").
61     */
62    public function getDarkTileUrlTemplate(): string;
63
64    /**
65     * Calculates optimal multi-point trip route (TSP - Travelling Salesperson Problem).
66     *
67     * @param array<int, GeoPoint> $points    Stop points to visit (minimum 2 points).
68     * @param bool                 $roundtrip Whether route should return to start point (default true).
69     * @return RouteResultDto|null Calculated optimal itinerary or null on error.
70     */
71    public function optimizeTrip(array $points, bool $roundtrip = true): ?RouteResultDto;
72
73    /**
74     * Returns configured API base URL.
75     */
76    public function getApiUrl(): string;
77
78    /**
79     * Returns configured API key.
80     */
81    public function getApiKey(): string;
82}