Ho sviluppato e donato un modulo open source a Mage-OS Lab: MageOS_StoreLocator, un modulo store locator completo per Mage-OS e Magento 2.

Cosa fa

Il modulo permette ai merchant di gestire i propri punti vendita fisici direttamente dall’admin di Magento, e ai clienti di trovare il negozio più vicino in storefront tramite ricerca testuale e geolocalizzazione.

Lato admin, c’è un CRUD completo sotto Stores → Store Locator → Manage Stores: per ogni negozio si gestiscono indirizzo, coordinate geografiche, orari di apertura per ogni giorno della settimana e visibilità per store view. La configurazione globale del modulo è sotto Stores → Configuration → Store Locator e copre provider mappa, API key, zoom predefinito, raggio di ricerca, unità di distanza, toggle geolocalizzazione e giorni di chiusura ricorrenti.

Doppio provider mappa

Il modulo supporta due provider: Google Maps (richiede una API key, da configurare nel backend — viene salvata cifrata) e Leaflet/OpenStreetMap, che non richiede nessuna chiave e nessun costo. Si sceglie in configurazione.

Frontend Hyvä

Il template storefront è scritto per Hyvä, con Tailwind CSS e Alpine.js. La logica specifica di ciascun provider mappa è isolata in view/frontend/web/js/store-locator-map.js, così è semplice estendere o sostituire il provider senza toccare il resto.

L’URL della pagina è configurabile — default /storelocator — e viene gestita da un router custom. La CSP whitelist per i domini esterni dei provider mappa è già inclusa.

REST API e testing

Il modulo espone endpoint REST per search, get, save e delete, protetti dalla risorsa ACL MageOS_StoreLocator::store. È disponibile anche un comando CLI per popolare negozi demo:

bin/magento storelocator:demo:create

I test unitari vivono in Test/Unit e si eseguono con PHPUnit dalla root di Magento.

Installazione

bin/magento module:enable MageOS_StoreLocator
bin/magento setup:upgrade
bin/magento cache:flush

Perché l’ho donato a Mage-OS Lab

Perché uno store locator è una funzionalità che serve a molti progetti e che non dovrebbe essere qualcosa da ricostruire ogni volta da zero o da acquistare come estensione commerciale. Averla disponibile come modulo open source, sotto l’ombrello di Mage-OS, ha senso — sia per la community che per chi costruisce progetti su questa piattaforma ogni giorno.

Il codice è su GitHub: github.com/mage-os-lab/module-store-locator