Looking to hire Laravel developers? Try LaraJobs

laravel-geotools maintained by colibri-informatique

Description
Generic geolocation for Laravel Eloquent models: address value object, pluggable geocoding, Haversine distance scopes, automatic coordinates, optional Leaflet map and Filament field.
Last update
2026/11/16 10:44 (dev-main)
License
Links
Downloads
2

Comments
comments powered by Disqus

Laravel GeoTools

Géolocalisation générique pour n’importe quel modèle Eloquent : adresse normalisée, géocodage interchangeable, coordonnées automatiques, recherche par distance (Haversine), carte Leaflet et champ Filament optionnels.

Ce package est né du projet Plateforme de l’Engagement et a été extrait pour être réutilisé sur d’autres applications Laravel (crowdfunding, annuaire, réseau de partenaires, etc.). Il ne connaît aucun modèle métier : Mission, User, Association, Projet ou n’importe quelle table peuvent l’utiliser.

Inspiré de lekoala/silverstripe-geotools, mais adapté aux conventions Laravel : trait Eloquent, scopes de requête, gestionnaire de drivers, value objects et intégration Filament.


Pourquoi un package dédié ?

Avant extraction, plusieurs briques existantes ont été examinées :

Brique Ce qu’elle apporte Pourquoi elle ne suffit pas ici
spatie/geocoder Intégration de Geocoder PHP, géocodage et géocodage inverse Ne gère ni les modèles Eloquent, ni la persistance des coordonnées, ni les scopes de distance ; l’API cible est un tableau ou une adresse libre
geocoder-php/nominatim-provider Provider Nominatim maintenu Fournit uniquement le client HTTP ; toute la logique applicative reste à écrire
matanyadaev/laravel-eloquent-spatial Types spatiaux et requêtes géographiques Exige un SGBD spatial (PostGIS, MySQL spatial) et des colonnes geometry, alors que les projets cibles stockent souvent latitude/longitude en decimal
grimzy/laravel-mysql-spatial Colonnes et index spatiaux MySQL MySQL uniquement, pas de SQLite, pas de géocodage
toin0u/geotools-laravel Intégration du composant Geotools Projet ancien, peu adapté aux versions récentes de Laravel, pas d’intégration Eloquent/Filament
laravel-geotools (ce package) Adresse + coordonnées, drivers, auto-géocodage, distance SQL, carte, Filament Volontairement sans PostGIS et sans routing

Le package ne réinvente pas les clients de géocodage : le driver Nominatim est volontairement simple, et un driver existant peut être branché via GeoTools::extend().


Fonctionnalités

  • Value objects Address et Coordinates, indépendants du modèle et validés.
  • Trait Geolocalisable pour tout modèle Eloquent, avec colonnes standards ou personnalisées.
  • Géocodage désactivé par défaut (driver = null) : aucun appel réseau involontaire.
  • Drivers fournis : null, nominatim. Drivers maison via GeoTools::extend().
  • Géocodage automatique à la création et au changement d’adresse, sans écraser des coordonnées saisies manuellement.
  • Cache configurable des réponses du géocodeur.
  • Distance en SQL via Haversine, sans PostGIS, avec pré-filtre par boîte englobante.
  • Scopes nearby(), withinBoundingBox(), withCoordinates(), missingCoordinates().
  • Commande geotools:geocode avec --force, --only-missing, --dry-run, --limit et --chunk.
  • Événements CoordinatesResolved et GeocodingFailed.
  • Composant Blade <x-geotools::map> et champ Filament MapPicker optionnels.
  • Traductions FR/EN et vues publiables.
  • Aucune dépendance à un domaine métier, aucun schéma imposé au-delà des colonnes d’adresse.

Installation

Depuis un dépôt local / VCS

{
    "repositories": [
        {
            "type": "path",
            "url": "../laravel-geotools",
            "options": { "symlink": true }
        }
    ]
}
composer require colibri-informatique/laravel-geotools:@dev

Le service provider est auto-découvert (ColibriInformatique\GeoTools\GeoToolsServiceProvider).

Publier la configuration

php artisan vendor:publish --tag=geotools-config

Publications optionnelles :

php artisan vendor:publish --tag=geotools-views
php artisan vendor:publish --tag=geotools-lang

Le package ne fournit aucune migration : les colonnes sont créées par la macro Blueprint::geolocalisable() (voir plus bas), ce qui permet de les intégrer à une migration existante ou à une nouvelle table.

Prérequis

Élément Version
PHP ^8.3
Laravel ^11, ^12, ^13
Filament ^5.0 (uniquement pour MapPicker)

Filament n’est pas une dépendance obligatoire : seule l’utilisation de ColibriInformatique\GeoTools\Filament\MapPicker le requiert.


Configuration

config/geotools.php après publication :

return [
    'geocoding' => [
        // Géocodage automatique des modèles qui utilisent le trait.
        'automatic' => env('GEOTOOLS_AUTOMATIC_GEOCODING', true),

        // Recalcule quand une colonne d'adresse change.
        'on_address_change' => true,

        // "null" (défaut) ou "nominatim".
        'driver' => env('GEOTOOLS_GEOCODER', 'null'),

        'cache' => [
            'store' => null,          // null = store de cache par défaut
            'ttl' => 60 * 60 * 24 * 30, // 0 = cache désactivé
        ],

        'nominatim' => [
            'endpoint' => env('GEOTOOLS_NOMINATIM_URL', 'https://nominatim.openstreetmap.org'),
            'user_agent' => env('GEOTOOLS_NOMINATIM_USER_AGENT', 'ColibriInformatique-GeoTools/0.1'),
            'email' => env('GEOTOOLS_NOMINATIM_EMAIL'),
            'language' => env('GEOTOOLS_NOMINATIM_LANGUAGE', 'fr'),
            'country_codes' => [],
            'timeout' => 10,
            'throttle_ms' => 0,
        ],
    ],

    'map' => [
        // ...
    ],
];

Variables d’environnement utiles :

GEOTOOLS_GEOCODER=nominatim
GEOTOOLS_AUTOMATIC_GEOCODING=true
GEOTOOLS_NOMINATIM_USER_AGENT="MonApp/1.0 (contact@example.org)"
GEOTOOLS_NOMINATIM_EMAIL=contact@example.org
GEOTOOLS_NOMINATIM_LANGUAGE=fr

Nominatim public : le service impose un User-Agent identifiant et une adresse de contact, ainsi qu’une limite d’usage (environ 1 requête/seconde). Pour un usage soutenu, auto-hébergez Nominatim, utilisez un fournisseur commercial, ou activez throttle_ms et le cache. Voir la politique d’usage OSM.


Schéma de données

La macro crée les colonnes d’adresse et de coordonnées, avec un index composite optionnel sur (latitude, longitude) :

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('missions', function (Blueprint $table): void {
            $table->id();
            $table->string('title');

            $table->geolocalisable();

            $table->timestamps();
        });
    }
};

Signature complète :

$table->geolocalisable(
    withAddress: true,        // street, street_extended, postal_code,
                              // locality, department, country_code
    withCoordinates: true,    // latitude, longitude (decimal 10,7)
    withIndex: true,          // index composite latitude + longitude
    defaultCountryCode: 'FR'  // valeur par défaut de country_code
);

Exemples :

// Table qui possède déjà son adresse, sans coordonnées pour l’instant.
$table->geolocalisable(withAddress: false);

// Coordonnées seulement, sans index.
$table->geolocalisable(withAddress: false, withIndex: false);

Colonnes créées :

Colonne Type
street string nullable
street_extended string nullable
postal_code string(16) nullable
locality string nullable
department string nullable
country_code string(2) nullable
latitude decimal(10,7) nullable
longitude decimal(10,7) nullable

Utiliser le trait

namespace App\Models;

use ColibriInformatique\GeoTools\Concerns\Geolocalisable;
use ColibriInformatique\GeoTools\Contracts\HasGeolocation;
use Illuminate\Database\Eloquent\Model;

final class Mission extends Model implements HasGeolocation
{
    use Geolocalisable;
}

HasGeolocation est optionnel : il sert à typer le code applicatif et la commande générique. Le trait fournit déjà toutes les méthodes du contrat.

Adresse et coordonnées

$mission->geoAddress();       // Address
$mission->hasCompleteAddress(); // rue + localité + pays
$mission->coordinates();      // Coordinates|null
$mission->hasCoordinates();   // bool
$mission->distanceTo(new Coordinates(48.8566, 2.3522)); // km|null

Une adresse est considérée complète lorsqu’elle possède au minimum une rue, une localité et un pays. C’est le seuil utilisé pour déclencher un géocodage : sans ces trois informations, aucun appel réseau n’est fait.

Colonnes personnalisées

Pour une table existante qui n’utilise pas les noms standards :

public function geoLatitudeColumn(): string
{
    return 'lat';
}

public function geoLongitudeColumn(): string
{
    return 'lng';
}

Les colonnes d’adresse restent street, street_extended, postal_code, locality, department, country_code. Pour une table très différente, le plus simple est d’utiliser un modèle dédié ou de faire une projection vers ces colonnes.

$fillable

Le trait complète automatiquement $fillable uniquement si le modèle utilise déjà une liste $fillable non vide. Un modèle en $guarded = [] reste libre : le trait ne restreint pas silencieusement ses assignations de masse.

Les coordonnées sont castées en float.


Géocodage automatique

Le trait écoute created et updated.

À la création :

  • si le géocodage automatique est désactivé, rien ne se passe ;
  • si le driver est null/none, rien ne se passe ;
  • si l’adresse est incomplète, rien ne se passe ;
  • si des coordonnées sont déjà fournies (formulaire, import, API), elles sont conservées ;
  • sinon l’adresse est géocodée et les coordonnées sont enregistrées avec saveQuietly().

À la mise à jour :

  • une modification explicite de latitude/longitude dans la même sauvegarde est prioritaire et n’est jamais écrasée ;
  • si les coordonnées sont absentes, elles sont résolues ;
  • si une colonne d’adresse change et que on_address_change est actif, les coordonnées sont recalculées ;
  • sinon rien ne se passe.

Pour désactiver globalement :

GEOTOOLS_AUTOMATIC_GEOCODING=false

Le géocodage explicite reste disponible :

$mission->geocode();        // ne remplace pas des coordonnées existantes
$mission->geocode(force: true); // recalcule

En cas d’échec réseau, l’exception est journalisée (Log::warning) et un événement GeocodingFailed est émis. La sauvegarde du modèle n’est pas interrompue.


Rechercher par distance

use ColibriInformatique\GeoTools\ValueObjects\Coordinates;

$center = new Coordinates(48.8566, 2.3522); // Paris

$missions = Mission::query()
    ->nearby($center, 50) // 50 km
    ->get();

foreach ($missions as $mission) {
    echo $mission->distance_km; // colonne ajoutée par le scope
}

nearby() :

  1. applique une boîte englobante pour réduire le nombre de lignes ;
  2. calcule la distance Haversine en SQL ;
  3. ajoute une colonne distance_km ;
  4. filtre sur le rayon et trie par distance croissante.

Le rayon doit être un nombre fini strictement positif. Les modèles sans coordonnées sont exclus.

Boîte englobante seule

Sur un SGBD sans fonctions trigonométriques, ou pour paginer un pré-filtre :

$query = Mission::query()->withinBoundingBox($center, 50);

// Puis affiner en PHP.
$results = $query->get()
    ->filter(fn (Mission $mission) => ($mission->distanceTo($center) ?? INF) <= 50)
    ->sortBy(fn (Mission $mission) => $mission->distanceTo($center));

La boîte englobante gère le passage de l’antiméridien (longitude ±180°).

Autres scopes

Mission::query()->withCoordinates()->get();    // latitude et longitude non nulles
Mission::query()->missingCoordinates()->get(); // au moins une coordonnée absente

SQL généré

Le calcul utilise :

  • radians, cos, sin, acos ;
  • min/max sur SQLite, least/greatest sur les autres drivers, pour clamper l’argument de acos entre -1 et 1 ;
  • un rayon injecté comme littéral numérique validé, et non comme binding PDO.

Pourquoi ce littéral ? Sur SQLite, un float lié via PDO peut être comparé comme du texte (107.5 < '100' est vrai), ce qui fausse silencieusement le filtre. Le package formate le rayon avec %F après validation, ce qui garantit un comportement identique sur SQLite, MySQL, MariaDB et PostgreSQL.

nearby() fonctionne donc sans PostGIS sur les bases supportées par Laravel. Il n’utilise pas d’index spatial : l’index composite (latitude, longitude) et la boîte englobante limitent la lecture, mais un très grand volume (plusieurs millions de lignes) justifiera PostGIS ou un moteur dédié.


Commande de géocodage

php artisan geotools:geocode "App\\Models\\Mission"

Options :

Option Effet
--force Recalcule même les modèles déjà géocodés
--only-missing Ne traite que les coordonnées absentes
--dry-run Compte les modèles concernés sans écrire
--limit=100 Nombre maximum de modèles traités (0 = tous)
--chunk=100 Taille des lots (lazyById)

Exemples :

php artisan geotools:geocode "App\\Models\\Mission" --only-missing --limit=500
php artisan geotools:geocode "App\\Models\\Association" --force --dry-run

La commande refuse un modèle qui n’utilise pas le trait et échoue si aucun géocodeur n’est configuré (sauf en --dry-run).


Carte Leaflet

Le composant Blade est utilisable sans Filament ni Livewire :

<x-geotools::map
    :latitude="$mission->latitude"
    :longitude="$mission->longitude"
    readonly
/>

En lecture seule, aucun marqueur n’est déplaçable et aucun clic ne modifie la position.

En édition Livewire, synchronisez deux propriétés :

<x-geotools::map
    :latitude="$latitude"
    :longitude="$longitude"
    latitude-path="latitude"
    longitude-path="longitude"
    height="360px"
/>

Chaque déplacement du marqueur ou clic sur la carte :

  • met à jour les propriétés Livewire via $wire.set() ;
  • émet un événement DOM geotools:coordinates-changed avec detail.latitude et detail.longitude.

Options disponibles :

Attribut Défaut
latitude, longitude null
latitude-path, longitude-path null
height 320px
zoom 15 (position connue)
default-zoom 6
default-center [46.603354, 1.888334] (France)
tile-url Tuiles OpenStreetMap
attribution © OpenStreetMap contributors
max-zoom 19
scroll-wheel-zoom false
readonly false
help Texte traduit, false pour masquer
leaflet-css, leaflet-js CDN Leaflet 1.9.4

La carte est protégée par wire:ignore : Livewire ne la recrée pas à chaque rendu. Le marqueur est déplaçable et un clic sur la carte le repositionne.

Les tuiles OpenStreetMap ont leur propre politique d’usage. Pour un trafic important, utilisez un fournisseur de tuiles ou un serveur interne, configurable via map.tile_url.


Champ Filament

MapPicker est un ViewField qui pilote deux champs voisins latitude/longitude. Il ne porte aucune valeur propre : il est dehydrated(false) et n’a donc pas besoin de colonne en base.

use ColibriInformatique\GeoTools\Filament\MapPicker;

MapPicker::make('location_map')
    ->label('Position')
    ->latitudeField('latitude')
    ->longitudeField('longitude')
    ->height('360px')
    ->zoom(15)
    ->defaultZoom(6)
    ->columnSpanFull();

Le nom du champ (location_map ci-dessus) est libre. Les chemins réels des champs latitude/longitude sont calculés à partir du statePath du champ carte : dans un Section, un Fieldset ou un Repeater, les deux champs doivent se trouver dans le même conteneur que la carte.

Section::make('Localisation')
    ->schema([
        TextInput::make('street')->label('Rue'),
        TextInput::make('postal_code')->label('Code postal'),
        TextInput::make('locality')->label('Ville'),
        TextInput::make('country_code')->label('Pays')->maxLength(2),

        Hidden::make('latitude'),
        Hidden::make('longitude'),

        MapPicker::make('location_map')
            ->latitudeField('latitude')
            ->longitudeField('longitude'),
    ]);

Le champ fonctionne sans Hidden si latitude/longitude sont déjà présents ailleurs dans le même schéma. Il est également utilisable en lecture seule via ->disabled() sur les champs voisins ou en n’affichant que le composant Blade.


Drivers personnalisés

Implémentez ColibriInformatique\GeoTools\Contracts\Geocoder :

namespace App\Geocoding;

use ColibriInformatique\GeoTools\Contracts\Geocoder;
use ColibriInformatique\GeoTools\ValueObjects\Address;
use ColibriInformatique\GeoTools\ValueObjects\Coordinates;

final class GoogleGeocoder implements Geocoder
{
    public function geocode(Address|string $address): ?Coordinates
    {
        // ...
    }

    public function reverse(Coordinates $coordinates): ?Address
    {
        // ...
    }
}

Puis, dans un service provider :

use ColibriInformatique\GeoTools\Facades\GeoTools;

public function boot(): void
{
    GeoTools::extend('google', fn ($app) => new \App\Geocoding\GoogleGeocoder(
        $app->make(\Illuminate\Http\Client\Factory::class),
    ));
}
GEOTOOLS_GEOCODER=google

Un driver string est également accepté dans Geocoder::geocode() : il est transmis tel quel au driver, qui décide comment l’interpréter.

Utilisation directe :

use ColibriInformatique\GeoTools\Facades\GeoTools;

$coordinates = GeoTools::geocode('12 rue de la Paix, 75002 Paris, FR');
$address = GeoTools::reverse(new Coordinates(48.8566, 2.3522));

GeoTools::driver('nominatim')->geocode('Paris');

Événements

Événement Contenu
CoordinatesResolved Model $model, Address $address, Coordinates $coordinates
GeocodingFailed Model $model, Address $address, Throwable $exception
use ColibriInformatique\GeoTools\Events\CoordinatesResolved;

Event::listen(function (CoordinatesResolved $event): void {
    logger()->info('Position résolue', [
        'model' => $event->model::class,
        'id' => $event->model->getKey(),
        'coordinates' => $event->coordinates->toArray(),
    ]);
});

GeocodingFailed est émis après le log d’avertissement. Il permet de brancher une alerte ou une file de reprise sans modifier le package.


Intégrer dans le projet Plateforme de l’Engagement

Le projet possède déjà une implémentation locale. Migration recommandée, sans toucher aux fichiers non commités :

1. Installer le package en path repository

composer require colibri-informatique/laravel-geotools:@dev

2. Remplacer le trait sur Mission

Dans app/Models/Mission.php :

-use App\Traits\Geolocalisable;
+use ColibriInformatique\GeoTools\Concerns\Geolocalisable;

Le trait du package fournit les mêmes colonnes et les mêmes scopes, avec en plus la gestion des drivers, du cache, des événements et des coordonnées manuelles.

3. Configurer le géocodeur

GEOTOOLS_GEOCODER=nominatim
GEOTOOLS_NOMINATIM_USER_AGENT="PlateformeEngagement/1.0 (contact@example.org)"
GEOTOOLS_NOMINATIM_EMAIL=contact@example.org

Sans ces variables, le driver reste null : le comportement actuel de géocodage réseau est désactivé, mais les scopes de distance continuent de fonctionner sur les coordonnées existantes.

4. Supprimer les doublons

Une fois la migration validée :

  • supprimer app/Traits/Geolocalisable.php ;
  • supprimer app/Infrastructure/Geocoding/Nominatim.php s’il n’est plus utilisé ;
  • retirer BlueprintMacros::register() de AppServiceProvider et supprimer app/Infrastructure/Database/BlueprintMacros.php.

La macro Blueprint::geolocalisable() du package est enregistrée par son service provider. Si celle de l’application est encore enregistrée, elle a la priorité : le package détecte Blueprint::hasMacro('geolocalisable') et ne l’écrase pas. Les deux versions créent les mêmes colonnes, mais celle du package ajoute l’index composite optionnel et defaultCountryCode.

5. Migrer la carte Filament

Dans MissionForm, remplacer le ViewField carte par :

use ColibriInformatique\GeoTools\Filament\MapPicker;

MapPicker::make('location_map')
    ->latitudeField('latitude')
    ->longitudeField('longitude')
    ->columnSpanFull();

Puis supprimer resources/views/partials/map/map.blade.php s’il n’est plus référencé.

6. Remplacer les appels applicatifs

L’ancien geocode() retournait void ; celui du package retourne bool. Les appels existants restent valides, mais peuvent désormais tester le résultat :

if ($mission->geocode()) {
    // coordonnées résolues
}

L’ancien déclenchement sur saved est remplacé par created + updated, ce qui évite un double appel lors d’une sauvegarde et distingue les créations des mises à jour.

7. Vérifier

php artisan geotools:geocode "App\\Models\\Mission" --dry-run
php artisan test

Limites et précautions

  • Pas de PostGIS : le package stocke latitude/longitude en decimal(10,7) et calcule la distance en SQL. Pour des recherches à très grande échelle, un index spatial et PostGIS resteront plus performants.
  • Fonctions SQL : nearby() requiert radians, cos, sin, acos et min/max (SQLite) ou least/greatest (MySQL, MariaDB, PostgreSQL). SQL Server n’est pas couvert.
  • SQLite : le rayon est injecté comme littéral numérique validé pour contourner la comparaison texte/réel de PDO. Les tests du package couvrent ce cas.
  • Pas de géocodage d’IP, pas de routing, pas d’autocomplétion d’adresse : le package se limite à l’adresse postale et aux coordonnées.
  • Nominatim public : respectez la politique OSM (User-Agent, contact, débit). Préférez un service auto-hébergé ou commercial en production soutenue.
  • Données personnelles : une adresse complète est une donnée personnelle. Le journal applicatif ne doit pas conserver d’adresses en clair sans base légale ni durée de conservation.
  • Coordonnées manuelles : elles sont préservées. Pour forcer un recalcul, utilisez geocode(force: true) ou geotools:geocode --force.
  • distance_km : le scope nearby() ajoute une colonne de ce nom. Évitez un conflit avec une colonne réelle du modèle.

Tests et qualité

composer test     # Pest
composer lint     # Pint en mode vérification
composer lint:fix # Pint en correction
composer phpstan  # Larastan niveau 6

Le package est testé sur SQLite en mémoire via Testbench, avec un géocodeur factice. Les tests couvrent le trait, les scopes de distance (dont l’antiméridien), le driver Nominatim (HTTP, cache, erreurs), la commande, la macro de migration et les composants carte.


Licence

MIT. Voir LICENSE.