Ako to funguje

Každé vyhľadávanie prechádza zoradenou pipeline pomenovaných poskytovateľov a vráti prvú nenulovú odpoveď. GeolocationProvider zmení GeolocationQuery (IP, súradnice alebo adresa) na Location; DistanceProvider zmení DistanceQuery (dva páry súradníc a spôsob dopravy) na Distance. Poskytovatelia, ktorí neimplementujú kontrakt potrebný pre dané volanie, sa preskočia:

use RoundlyConsulting\Geolocation\DataTransferObjects\Distance;
use RoundlyConsulting\Geolocation\DataTransferObjects\DistanceQuery;
use RoundlyConsulting\Geolocation\DataTransferObjects\GeolocationQuery;
use RoundlyConsulting\Geolocation\DataTransferObjects\Location;

// RoundlyConsulting\Geolocation\GeolocationProvider
public function locate(GeolocationQuery $query): ?Location;

// RoundlyConsulting\Geolocation\DistanceProvider
public function distance(DistanceQuery $query): ?Distance;

Pribalení poskytovatelia

Oba poskytovatelia MaxMind sú predvolene vypnutí a okamžite vracajú null, kým ich nezapnete a nedodáte prístupové údaje alebo cestu k databáze.

Pipeline

Poskytovatelia sa skúšajú v poradí pipeline; prednosť zmeníte preusporiadaním v konfigurácii:

// config/geolocation.php — consulted top to bottom, the first non-null answer wins
'pipeline' => ['maxmind_database', 'maxmind_web', 'ip2location', 'ipinfo', 'google', 'default'],

Mená v pipeline, ktoré nie sú v mape providers ani zaregistrované cez extend(), sa potichu preskočia. Poskytovateľ, ktorý dopyt nevie obslúžiť — napríklad Google pri IP alebo IP poskytovateľ pri adrese — vráti null a skúsi sa ďalší. Aj chybové odpovede sa zmenia na null, takže zlyhávajúci poskytovateľ odovzdá slovo ďalšiemu.

Rovnako sa počíta poskytovateľ, ktorého API sa vôbec nedá dosiahnuť — timeout, zlyhanie DNS, odmietnuté spojenie: pipeline namiesto výnimky pokračuje ďalej a chybu ohlási, bez prístupových údajov, v udalosti LocationResolutionFailed. Niektoré chyby vyhľadávanie zámerne ukončia aj naďalej: RateLimitExceededException pri rýchlom zlyhaní, chýbajúca alebo poškodená databáza MaxMind a akákoľvek výnimka z vášho vlastného poskytovateľa (pozrite Výnimky).

Prázdne odpovede

Prázdna odpoveď sa počíta ako žiadna odpoveď. Location bez časti adresy, bez krajiny a so súradnicami 0,0 ($location->isEmpty()) — napríklad odpoveď IP2Location pre súkromnú IP — sa preskočí a opýta sa ďalší poskytovateľ. Location, ktorú dostanete, preto vždy niečo určuje, hoci hrubej zhode podľa IP môže chýbať mesto alebo krajina.

Čo predvolene volá sieť

S dodanou konfiguráciou pošle vyhľadávanie IP adresu na api.ip2location.io a potom na ipinfo.io, aj bez IP2LOCATION_API_KEY či IPINFO_TOKEN (požiadavka je potom neautentifikovaná). Vyhľadávanie adresy či súradníc a každá vzdialenosť idú na Google, ktorý na úspech potrebuje GOOGLE_MAPS_API_KEY. maxmind_database a default sa siete nikdy nedotknú a v testoch Geolocation::fake() nevolá žiadneho poskytovateľa.

Pipeline zúžte na poskytovateľov, ku ktorým máte prístupové údaje — každý, kto v nej zostane, sa postupne skúša, kým niekto neodpovie, a každý HTTP poskytovateľ znamená skutočnú odchádzajúcu požiadavku:

// Only the providers you have credentials for: offline first, fallback last
'pipeline' => ['maxmind_database', 'ipinfo', 'google', 'default'],

Ak majú IP návštevníkov zostať na vašich serveroch, ponechajte len offline poskytovateľov:

// Keep visitor IPs on your own servers — no provider here calls the network
'pipeline' => ['maxmind_database', 'default'],

Záložná poloha

Poskytovateľ default odpovedá, až keď nastavíte záložnú polohu (akúkoľvek hodnotu default.*). S dodanými prázdnymi hodnotami odpovie tiež null, takže nevyriešené vyhľadávanie zostane null. Keď odpovie, Location má typ GeolocationType::Default, takže zálohu od skutočného výsledku rozlíšite:

use RoundlyConsulting\Geolocation\Enum\GeolocationType;
use RoundlyConsulting\Geolocation\Facades\Geolocation;

$location = Geolocation::locateRequest();

if ($location?->type === GeolocationType::Default) {
    // No real provider answered — this is the configured fallback location.
}

Záložná poloha sa nikdy necachuje — odpovedala len preto, že skutoční poskytovatelia nie, takže ďalšie volanie sa ich opýta znova. Ak chcete, aby vyhľadávanie bez výsledku vrátilo null (a udalosť LocationResolutionFailed), nechajte default.* prázdne alebo default z pipeline odstráňte.

Pomenovaní poskytovatelia

Kľúč providers je pomenovaná mapa — pipeline, provider() aj using() odkazujú na poskytovateľov menom. Ak sa žiadne meno z pipeline s mapou nezhoduje, použije sa poradie mapy. Plochý zoznam tried už balík neprijíma:

use RoundlyConsulting\Geolocation\Providers\DefaultLocationProvider;
use RoundlyConsulting\Geolocation\Providers\IpInfoProvider;

// Every entry needs a name — the pipeline and provider() address providers by it
'providers' => [
    'ipinfo' => IpInfoProvider::class,
    'default' => DefaultLocationProvider::class,
],

// An unnamed entry throws UnknownProviderException on the first lookup
'providers' => [IpInfoProvider::class],