Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
1 / 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;
12
13/**
14 * Interface contract for third-party or local map tile and geocoding providers.
15 *
16 * @package App\Modules\Map\Domain\Repository
17 */
18interface MapProviderInterface
19{
20    /**
21     * Unique identifier name for provider (e.g. "ammonly_local", "maptiler", "osm_public").
22     */
23    public function getName(): string;
24
25    /**
26     * Human-friendly label of the provider.
27     */
28    public function getLabel(): string;
29
30    /**
31     * URL template for raster tiles.
32     *
33     * @param bool $darkMode Whether to return dark theme tile URL.
34     */
35    public function getTileUrlTemplate(bool $darkMode = false): string;
36
37    /**
38     * Checks if coordinates fall within this provider's primary high-detail coverage.
39     *
40     * @param float $latitude  WGS-84 latitude.
41     * @param float $longitude WGS-84 longitude.
42     */
43    public function supportsRegion(float $latitude, float $longitude): bool;
44
45    /**
46     * Executes forward geocoding query.
47     *
48     * @param string $query Address search query.
49     * @param int    $limit Max candidates.
50     * @return array<int, GeoPoint>
51     */
52    public function geocode(string $query, int $limit = 5): array;
53
54    /**
55     * Executes reverse geocoding from latitude and longitude.
56     *
57     * @param float $latitude  WGS-84 latitude.
58     * @param float $longitude WGS-84 longitude.
59     */
60    public function reverseGeocode(float $latitude, float $longitude): ?GeoPoint;
61
62    /**
63     * Returns true if provider is configured with valid credentials/endpoints and active.
64     */
65    public function isAvailable(): bool;
66
67    /**
68     * Returns last measured or estimated response latency in milliseconds.
69     */
70    public function getLatencyMs(): float;
71}