Download the PHP package andydefer/laravel-locationiq without Composer

Laravel LocationIQ

Intégration Laravel du SDK LocationIQ/Nominatim pour le géocodage, les itinéraires, les fuseaux horaires et les matrices de durées/distances.

Table des matières

1. Introduction
2. Installation
3. Configuration
4. Routes exposées
5. Utilisation
6. Contrats et extension
7. Gestion des erreurs
8. Tests
9. Sécurité
10. Compatibilité

1. Introduction

Objectif

andydefer/laravel-locationiq expose les opérations LocationIQ et Nominatim (solde de quota, fuseau horaire, itinéraires, matrices de durées/distances, reverse geocoding) sous forme d'endpoints HTTP Laravel prêts à l'emploi.

Le package s'appuie sur andydefer/php-locationiq, qui contient toute la logique métier et les objets typés (Record, Response, Data, Graph, Collection). Laravel LocationIQ n'ajoute que la couche transport : routes, validation, injection.

Ce que le package fournit

• 5 endpoints HTTP : solde de quota, fuseau horaire, itinéraires, matrices, reverse geocoding.
• 4 FormRequest : validation stricte des payloads et construction des Record typés du SDK.
• 5 Action : résolvent le client LocationIQ ou Nominatim via la configuration, appellent l'opération correspondante et renvoient la Data typée. En cas d'erreur, l'action propage un ErrorResponseData normalisé.
• Une configuration unique : clé API, URL régionale, URL Nominatim, User-Agent, profil de directions par défaut.
• Deux points d'extension : remplacer le client LocationIQ (locationiq_client_fqcn) ou le client Nominatim (nominatim_client_fqcn) sans modifier le package.

Ce que le package ne fait pas

• Aucune authentification. Les routes sont publiées sans middleware.
• Aucune persistance. Le package ne touche pas à la base de données.
• Aucune mise en cache. À implémenter côté application hôte selon les besoins.

2. Installation

Le LocationIqServiceProvider est découvert automatiquement par Laravel.

3. Configuration

3.1 Publier les fichiers

• Config publiée dans config/locationiq.php.
• Routes publiées dans routes/locationiq.php.

3.2 Charger les routes

Les routes ne sont pas chargées automatiquement. Charge-les explicitement depuis ton application :

Tu contrôles ainsi le préfixe, les middlewares et l'ordre de chargement.

3.3 Fichier de configuration

3.4 Clés de configuration

3.5 Variables d'environnement

3.6 Cas concret : configuration Afya (RDC)

4. Routes exposées

Le fichier routes/locationiq.php déclare cinq endpoints, tous en POST, sous le préfixe locationiq.

5. Utilisation

5.1 Récupérer le solde de quota

Requête :

Aucun paramètre.

Réponse succès (200) :

5.2 Résoudre un fuseau horaire

Requête :

Paramètres :

Réponse succès (200) :

5.3 Calculer un itinéraire

Requête :

Paramètres :

Réponse succès (200) :

Polymorphisme géré : LocationIQ retourne tantôt un objet unique, tantôt un tableau. Le SDK normalise toujours en collection typée.

5.4 Calculer une matrice de durées/distances

Calcule les durées et/ou distances des trajets les plus rapides entre toutes les paires de coordonnées fournies. Utile pour comparer rapidement plusieurs points (livraisons, tournées, répartition géographique).

Requête minimale :

Requête complète :

Paramètres :

Réponse succès (200) :

Comprendre la matrice

• Non symétrique. durations[0][1] peut différer de durations[1][0] à cause des sens uniques, priorités aux carrefours et feux de circulation. C'est la réalité du trafic — et c'est précisément l'intérêt de l'endpoint Matrix.
• Diagonale à zéro. Le trajet d'un point vers lui-même est toujours 0.0.
• Distances routières. Ce ne sont pas des distances à vol d'oiseau, mais la longueur du chemin routier le plus rapide.
• Cellules sans route. Si LocationIQ ne trouve pas de route, la cellule vaut -1.0 (sentinel FloatMatrixVO::NO_ROUTE_SENTINEL). Vérifie avec isNoRoute($row, $column).

Restreindre les sources et destinations

Par défaut, LocationIQ calcule la matrice complète N×N. Tu peux restreindre avec des index de coordonnées (base 0) :

• sources: [0] → matrice 1×N (départs depuis la coordonnée #0 uniquement).
• destinations: [1, 2] → matrice N×2.
• sources: [0] et destinations: [1, 2] → matrice 1×2.

Utile quand tu as un entrepôt fixe et plusieurs destinations. Économie de quota et de temps de calcul.

Fallback : paires non routables

Si tu veux garantir qu'aucune cellule ne soit vide, active le fallback :

• fallback_speed : vitesse en m/s utilisée pour estimer la durée à partir de la distance à vol d'oiseau.
• fallback_coordinate : input (coordonnée envoyée) ou snapped (coordonnée projetée sur le réseau routier). snapped est plus cohérent avec le reste de la matrice.

5.5 Reverse geocoding

Requête :

Paramètres :

Réponse succès (200) :

6. Contrats et extension

6.1 LocationIqConfigInterface

Contrat de la configuration. Utilisé par le ServiceProvider pour construire les clients et par les Action pour les résoudre.

6.2 ErrorDescribable

Contrat hérité du package andydefer/laravel-nemesis. Tout enum d'erreur qui l'implémente expose une API cohérente :

• getHttpStatusCode(): HttpStatusCode
• getMessage(): string
• getLabel(): string
• toResponseData(): ErrorResponseData
• toJsonResponseFactory(): ResponseFactory

6.3 ErrorCode

Enum qui implémente ErrorDescribable. Couvre les codes d'erreur LocationIQ et Nominatim.

6.4 Remplacer le client LocationIQ

Contraintes :

• La classe doit implémenter LocationIqClientInterface.
• Son constructeur doit être auto-résolvable par le conteneur Laravel.

6.5 Remplacer le client Nominatim

Contraintes :

• La classe doit implémenter NominatimClientInterface.
• Son constructeur doit être auto-résolvable par le conteneur Laravel.

6.6 Binder les interfaces manuellement

L'option bind n'a d'effet que si les clés locationiq_client_fqcn et nominatim_client_fqcn restent égales à leurs valeurs par défaut.

7. Gestion des erreurs

Le package distingue trois niveaux.

7.1 Validation (HTTP 422)

Les FormRequest rejettent les payloads invalides avant toute exécution.

7.2 Erreurs LocationIQ

L'action map le message brut vers un ErrorCode, puis renvoie un ErrorResponseData avec le bon code HTTP.

Correspondances message → code :

LocationIQ peut renvoyer InvalidOptions, NoTable ou NotImplemented dans le champ code avec un HTTP 200. Le SDK détecte ce cas et les mappe vers les codes d'erreur typés.

7.3 Erreurs SDK

Les Action capturent les exceptions levées par le SDK et les transforment en ErrorResponseData.

Note : les index sources et destinations hors plage sont rejetés au niveau de la validation (FormRequest::withValidator) avant d'atteindre le SDK. Ils produisent une erreur 422 sur sources.0 / destinations.0, pas sur errorCode.

8. Tests

Le package fournit un IntegrationTestCase basé sur orchestra/testbench. Chaque test enregistre le vrai endpoint via action_route(...) et remplace les clients HTTP bas niveau par des mocks (MockLocationIqClient, MockNominatimClient).

Structure d'un test

Les tests suivent la convention AAA :

Restreindre les valeurs en test

Si tu veux tester avec une configuration alternative :

9. Sécurité

• Routes non protégées par défaut. Ajoute tes middlewares (auth:sanctum, throttle:60,1, signature HMAC…) dans le fichier publié.
• LOCATIONIQ_API_KEY côté serveur uniquement. Ne jamais l'exposer au frontend.
• NOMINATIM_USER_AGENT obligatoire en production. Nominatim peut bloquer les requêtes sans User-Agent identifiable.
• Rate limit Nominatim : 1 requête/seconde sur l'instance publique. Prévoir un throttling côté application.
• Rate limit LocationIQ : sur les plans gratuits, minimum 1 seconde entre deux requêtes (Rate Limited Second). Prévoir un throttling côté application si tu enchaînes plusieurs appels Matrix ou Directions.
• Validation stricte : toutes les entrées (coordonnées, formats, profils, langues, annotations, sources, destinations) sont validées par les FormRequest avant tout appel HTTP.
• Restriction des formats Nominatim : seuls json, jsonv2, geojson et geocodejson sont acceptés.
• Restriction des profils Directions et Matrix : seuls driving et walking sont acceptés.
• Limite de coordonnées : 2 à 25 par requête Directions ou Matrix (limite imposée par l'API).
• Aucune donnée sensible persistée. Le package ne stocke rien.

10. Compatibilité

Licence