splitfire / laravel-api-geo
Laravel client for the Splitfire geocoding API (api-geo).
Requires
- php: ^8.2
- guzzlehttp/guzzle: ^7.2|^8.0
- illuminate/http: ^8.83|^9.0|^10.0|^11.0|^12.0|^13.0
- illuminate/support: ^8.83|^9.0|^10.0|^11.0|^12.0|^13.0
Requires (Dev)
- laravel/pint: ^1.13
- nesbot/carbon: ^2.62.1|^3.0
- opis/json-schema: ^2.3
- orchestra/testbench: ^6.48|^7.0|^8.0|^9.0|^10.0|^11.0
- phpunit/phpunit: ^9.6|^10.5|^11.5|^12.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Client Laravel de l'API de géocodage Splitfire (api-geo), joignable à travers la passerelle api-gateway sous /geo. Le contrat de réponse de référence est docs/contract.md d'api-geo.
Compatible Laravel 8.83 à 13, PHP 8.2 et plus.
Installation
composer require splitfire/laravel-api-geo
La clé de service est une clé sfg_live_… de la passerelle portant les portées geo:address (/search) et geo:reverse (/reverse). Côté serveur, elle ne doit pas être restreinte par origine ; une restriction par IP reste possible.
| Variable | Défaut | Rôle |
|---|---|---|
API_GEO_KEY |
requise | clé de service |
API_GEO_URL |
https://api.services.splitfire.fr/geo |
URL de base, passerelle comprise |
API_GEO_TIMEOUT |
8 |
délai de réponse, en secondes |
API_GEO_CONNECT_TIMEOUT |
2 |
délai de connexion, en secondes |
API_GEO_RETRY_TIMES |
1 |
nouvelles tentatives sur une indisponibilité |
API_GEO_RETRY_SLEEP_MS |
1000 |
attente avant une nouvelle tentative |
php artisan vendor:publish --tag=api-geo-config publie config/api-geo.php. Un fichier partiel est complété par les valeurs par défaut. Une valeur invalide (délai vide, infini ou sous la milliseconde, URL vide) lève une InvalidArgumentException à la première résolution du client.
Utilisation
Par injection de Splitfire\ApiGeo\Contracts\Geocoder ou par la façade ApiGeo :
use Splitfire\ApiGeo\Data\Coordinates; use Splitfire\ApiGeo\Data\FeatureType; use Splitfire\ApiGeo\Facades\ApiGeo; use Splitfire\ApiGeo\Query\ReverseQuery; use Splitfire\ApiGeo\Query\SearchQuery; $results = ApiGeo::search('8 boulevard du port amiens'); $results = ApiGeo::search( SearchQuery::for('8 bd du port')->autocomplete(false)->postcode('80000')->type(FeatureType::Address)->limit(1) ); $results = ApiGeo::reverse(ReverseQuery::at(new Coordinates(lat: 49.8974, lon: 2.2900))); foreach ($results as $feature) { $feature->label; // 8 Boulevard du Port 80000 Amiens $feature->coordinates->lat; // 49.897443 $feature->citycode; // 80021, ou null } $results->attribution; // licence de la BAN, à afficher $results->meta->requestId; // X-Request-Id, pour corréler avec les journaux de la passerelle $results->meta->rateLimit?->remaining;
SearchQueryacceptelimit,autocomplete,type,postcode,citycode,departmentCode,regionCodeetnear.autocomplete(false)convient au géocodage d'une adresse complète.- Une requête est validée à sa construction, avec les règles du contrat : une valeur refusée lève
InvalidQuerysans appel, donc sans consommer de quota. - Les coordonnées sont tronquées comme le fait geo : 3 décimales pour
near, 4 pourreverse. - Zéro résultat n'est pas une erreur :
$results->isEmpty(). - Un résultat d'un type que cette version ne connaît pas est écarté.
Feature::$idchange à chaque publication de la BAN : il ne doit pas être conservé.ApiGeo::withRequestId($id)renvoie un client qui transmet cet identifiant. Un identifiant que la passerelle remplacerait (vide, plus de 128 caractères, hors ASCII imprimable) n'est pas transmis : elle en génère un.
Erreurs
Les exceptions d'une requête implémentent Splitfire\ApiGeo\Exceptions\ApiGeoException. Celles qui viennent d'une réponse étendent RequestFailed et portent errorCode, status, parameter, retryAfter et meta (requestId, rateLimit).
| Exception | Cas |
|---|---|
InvalidQuery |
requête refusée avant tout appel ; errorCode et parameter comme dans le contrat |
RequestRejected |
400 de geo |
AccessDenied |
clé absente, invalide, révoquée ou expirée, projet suspendu, portée, origine ou IP refusée |
QuotaExceeded |
limite minute ou jour (429), plafond mensuel (402) |
ServiceUnavailable |
passerelle, cache ou moteur indisponible, délai dépassé, connexion refusée, service désactivé |
UnexpectedResponse |
réponse hors contrat |
retryAfter reprend Retry-After, en secondes. La passerelle ne l'envoie que sur un 429 : pour une QuotaExceeded sans Retry-After, comme le plafond mensuel (402), il prend RateLimit-Reset, ici la fin du mois.
Une ServiceUnavailable est retentée API_GEO_RETRY_TIMES fois quand elle est passagère (isTransient(), faux pour service_disabled). Les autres erreurs ne le sont pas : un job peut relâcher une QuotaExceeded avec $this->release($e->retryAfter ?? 60).
Cache
Le package ne met rien en cache. Chaque appel passe par la passerelle et compte dans le quota, même servi depuis le cache d'api-geo. Une FeatureCollection se met en cache sous sa forme JSON, que FeatureCollection::fromArray() reconstruit :
$key = 'geo:search:'.sha1(mb_strtolower(trim($text))); $json = Cache::remember($key, now()->addWeek(), fn () => json_encode(ApiGeo::search($text))); $results = FeatureCollection::fromArray(json_decode($json, true));
Le JSON évite de mettre en cache un objet PHP, que refuse un cache configuré avec 'serializable_classes' => false, valeur du config/cache.php actuel de Laravel. meta est vide sur un résultat reconstruit : le quota et le request id d'origine n'ont plus cours.
Tests dans une application
Le client passe par la façade Http, Http::fake() s'applique :
Http::fake(['api.services.splitfire.fr/geo/*' => Http::response($featureCollection)]);
Ou par substitution du contrat : $this->app->instance(Geocoder::class, $fake).
Développement
PHP et Composer tournent dans Docker (PHP_VERSION, 8.2 par défaut) :
docker compose run --rm php composer update docker compose run --rm php vendor/bin/phpunit docker compose run --rm php composer lint
Les versions de Laravel 8 à 11 ont des avis de sécurité ouverts : Composer refuse de les installer sans --no-blocking. Pour tester une version précise :
docker compose run --rm php composer update --no-blocking --with 'orchestra/testbench:6.*'
Les tests restent compatibles PHPUnit 9 à 12 : méthodes préfixées test_ et fournisseurs de données déclarés en annotation et en attribut. Les fixtures de tests/Fixtures sont validées contre geo-v1.schema.json, copie du schéma d'api-geo.