PHPackages                             ilbullo/geo-service - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. ilbullo/geo-service

ActiveLibrary[Utility & Helpers](/categories/utility)

ilbullo/geo-service
===================

A Laravel package for polymorphic geolocation and real-time mapping.

V1.1.11(1mo ago)08MITPHPPHP ^8.1

Since Apr 14Pushed 1mo agoCompare

[ Source](https://github.com/ilbullo/geo-service)[ Packagist](https://packagist.org/packages/ilbullo/geo-service)[ RSS](/packages/ilbullo-geo-service/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (2)Versions (14)Used By (0)

🇮🇹 Italiano - Guida Rapida
--------------------------

[](#-italiano---guida-rapida)

Benvenuto nel manuale tecnico ufficiale di **GeoService**. Questa guida ti spiegherà ogni singolo ingranaggio del package, dalla cattura del segnale GPS alla visualizzazione dinamica sulla mappa.

Il package si basa su tre pilastri fondamentali: **Cattura** (Input), **Trasformazione** (Logica) e **Visualizzazione** (Output).

---

🛠 1. Preparazione dell'Infrastruttura
-------------------------------------

[](#-1-preparazione-dellinfrastruttura)

Prima di muovere i primi passi, il tuo ambiente Laravel deve essere pronto ad accogliere i dati geografici.

### Requisiti Frontend

[](#requisiti-frontend)

Il package utilizza **Leaflet.js** per il rendering cartografico e **Alpine.js** per la gestione degli eventi. Nel tuo layout principale (`app.blade.php`), inserisci:

HTML

```

```

### Configurazione Globale (`config/geo-service.php`)

[](#configurazione-globale-configgeo-servicephp)

Il cuore visivo si gestisce qui. Puoi definire icone diverse per ogni classe di modello o un'icona di fallback:

- **`refresh_interval`**: Definisce ogni quanto la mappa deve interrogare il server per aggiornare le posizioni (es: '10s').
- **`default_icon`**: Array contenente URL, dimensioni e punto di ancoraggio dell'icona standard.
- **`icons`**: Un mapping `Classe => URL` per assegnare automaticamente icone a modelli diversi (es: `Vehicle::class => '/truck.png'`).

---

📡 2. GeoTracker: Il sensore di movimento
----------------------------------------

[](#-2-geotracker-il-sensore-di-movimento)

Il componente `GeoTracker` è l'interfaccia tra il dispositivo fisico e il database.

### Come funziona

[](#come-funziona)

1. **Rilevamento**: All'avvio, il componente richiede i permessi GPS al browser.
2. **Sincronizzazione**: Utilizza il metodo `updatePosition()` per salvare le coordinate nella tabella polimorfica `locations`.
3. **Persistenza**: Salva latitudine, longitudine, il provider (es: 'browser') e l'ultimo timestamp utile (`last_seen_at`).

### Utilizzo nel codice

[](#utilizzo-nel-codice)

Puoi inizializzare il tracker per l'utente autenticato o per un'entità specifica:

HTML

```
@livewire('geo-tracker')

@livewire('geo-tracker', ['model' => $veicolo])

```

---

🧠 3. La Logica: MapService e DTO
--------------------------------

[](#-3-la-logica-mapservice-e-dto)

Questa è la parte "invisibile" che garantisce la pulizia del codice (SOLID).

- **`MapMarkerDTO`**: Trasforma i dati grezzi del database in un oggetto standardizzato e serializzabile in JSON per il frontend, garantendo che Leaflet riceva sempre dati validi.
- **`MapService`**: Si occupa di filtrare i modelli e generare i marker. Recupera le `Location` associate ai modelli passati, estrae l'HTML del popup e l'URL dell'icona corretta.

### L'Interfaccia `GeolocatablePopup`

[](#linterfaccia-geolocatablepopup)

Per rendere un modello "mappabile", deve implementare questo contratto:

1. **`toMapPopup()`**: Ritorna la stringa HTML che apparirà cliccando sul marker.
2. **`getMapIcon()`**: Permette a una singola istanza (es: un mezzo in emergenza) di cambiare icona dinamicamente, ignorando le impostazioni globali.

---

🗺 4. GeoMap: La Centrale Operativa
----------------------------------

[](#-4-geomap-la-centrale-operativa)

Il componente `GeoMap` visualizza i dati e gestisce il refresh automatico (polling).

### Passare modelli personalizzati alla mappa

[](#passare-modelli-personalizzati-alla-mappa)

Questa è la funzione più potente: puoi decidere **esattamente cosa mostrare** sulla mappa passando un array o una collezione di modelli alla proprietà `$models`.

**Scenario****Esempio di Codice****Intera Flotta**`@livewire('geo-map', ['models' => Vehicle::all()])`**Solo Mezzi Attivi**`@livewire('geo-map', ['models' => Vehicle::where('status', 'moving')->get()])`**Singolo Utente**`@livewire('geo-map', ['models' => [$user]])`**Mix Polimorfico**`@livewire('geo-map', ['models' => $fleet->merge($pointsOfInterest)])`### Ciclo di vita del refresh

[](#ciclo-di-vita-del-refresh)

1. Il componente si avvia e carica i marker iniziali tramite `loadMap()`.
2. Ogni `X` secondi (configurati nel file `geo-service.php`), il componente riesegue la query.
3. L'evento `map-updated` viene inviato al frontend.
4. **Alpine.js** riceve i nuovi DTO, pulisce i vecchi marker e posiziona quelli nuovi senza ricaricare la pagina.

---

💎 5. Riassunto dei Trait
------------------------

[](#-5-riassunto-dei-trait)

Per rendere operativo un tuo modello Eloquent (es. `App\Models\Truck`), ti basta aggiungere queste righe:

PHP

```
use IlBullo\GeoService\Traits\HasGeolocation;
use IlBullo\GeoService\Traits\HasGeolocatablePopup;
use IlBullo\GeoService\Contracts\GeolocatablePopup;

class Truck extends Model implements GeolocatablePopup
{
    use HasGeolocation;      // Gestisce la relazione con la tabella locations
    use HasGeolocatablePopup; // Fornisce implementazioni base per icone e popup

    public function toMapPopup(): string
    {
        return "Camion: {$this->license_plate}";
    }
}

```

Ora il tuo sistema di gestione flotta è pronto. Puoi tracciare mezzi, visualizzarli filtrati per categoria e vederli muoversi in tempo reale con zero configurazione aggiuntiva sul frontend.

🇺🇸 English - Quick Start
------------------------

[](#-english---quick-start)

Welcome to the official **GeoService** technical manual. This guide explains every gear within the package, from capturing the GPS signal to dynamic map visualization.

The package is built on three fundamental pillars: **Capture** (Input), **Transformation** (Logic), and **Visualization** (Output).

---

🛠 1. Infrastructure Preparation
-------------------------------

[](#-1-infrastructure-preparation)

Before taking your first steps, your Laravel environment must be ready to receive geographic data.

### Frontend Requirements

[](#frontend-requirements)

The package uses **Leaflet.js** for cartographic rendering and **Alpine.js** for event management. In your main layout (`app.blade.php`), include the following:

HTML

```

```

### Global Configuration (`config/geo-service.php`)

[](#global-configuration-configgeo-servicephp)

The visual core is managed here. You can define different icons for each model class or a fallback icon:

- **`refresh_interval`**: Defines how often the map should poll the server to update positions (e.g., '10s').
- **`default_icon`**: An array containing the URL, dimensions, and anchor point of the standard icon.
- **`icons`**: A `Class => URL` mapping to automatically assign icons to different models (e.g., `Vehicle::class => '/truck.png'`).

---

📡 2. GeoTracker: The Motion Sensor
----------------------------------

[](#-2-geotracker-the-motion-sensor)

The `GeoTracker` component serves as the interface between the physical device and the database.

### How it Works

[](#how-it-works)

1. **Detection**: Upon startup, the component requests GPS permissions from the browser.
2. **Synchronization**: It utilizes the `updatePosition()` method to save coordinates into the polymorphic `locations` table.
3. **Persistence**: It saves latitude, longitude, the provider (e.g., 'browser'), and the last known timestamp (`last_seen_at`).

### Code Usage

[](#code-usage)

You can initialize the tracker for the authenticated user or for a specific entity:

HTML

```
@livewire('geo-tracker')

@livewire('geo-tracker', ['model' => $vehicle])

```

---

🧠 3. The Logic: MapService and DTO
----------------------------------

[](#-3-the-logic-mapservice-and-dto)

This is the "invisible" part that ensures clean code (SOLID).

- **`MapMarkerDTO`**: Transforms raw database data into a standardized, JSON-serializable object for the frontend, ensuring Leaflet always receives valid data.
- **`MapService`**: Handles model filtering and marker generation. It retrieves the `Location` records associated with the passed models, extracting the popup HTML and the correct icon URL.

### The `GeolocatablePopup` Interface

[](#the-geolocatablepopup-interface)

To make a model "mappable," it must implement this contract:

1. **`toMapPopup()`**: Returns the HTML string that will appear when clicking the marker.
2. **`getMapIcon()`**: Allows a single instance (e.g., a vehicle in an emergency state) to dynamically change its icon, ignoring global settings.

---

🗺 4. GeoMap: The Command Center
-------------------------------

[](#-4-geomap-the-command-center)

The `GeoMap` component visualizes the data and manages automatic refresh (polling).

### Passing Custom Models to the Map

[](#passing-custom-models-to-the-map)

This is the most powerful feature: you can decide **exactly what to show** on the map by passing an array or a collection of models to the `$models` property.

**Scenario****Code Example****Entire Fleet**`@livewire('geo-map', ['models' => Vehicle::all()])`**Only Active Vehicles**`@livewire('geo-map', ['models' => Vehicle::where('status', 'moving')->get()])`**Single User**`@livewire('geo-map', ['models' => [$user]])`**Polymorphic Mix**`@livewire('geo-map', ['models' => $fleet->merge($pointsOfInterest)])`### Refresh Lifecycle

[](#refresh-lifecycle)

1. The component starts and loads initial markers via `loadMap()`.
2. Every `X` seconds (configured in `geo-service.php`), the component re-executes the query.
3. The `map-updated` event is dispatched to the frontend.
4. **Alpine.js** receives the new DTOs, clears old markers, and places new ones without a page reload.

---

💎 5. Trait Summary
------------------

[](#-5-trait-summary)

To make your Eloquent model (e.g., `App\Models\Truck`) operational, simply add these lines:

PHP

```
use IlBullo\GeoService\Traits\HasGeolocation;
use IlBullo\GeoService\Traits\HasGeolocatablePopup;
use IlBullo\GeoService\Contracts\GeolocatablePopup;

class Truck extends Model implements GeolocatablePopup
{
    use HasGeolocation;      // Manages the relationship with the locations table
    use HasGeolocatablePopup; // Provides base implementations for icons and popups

    public function toMapPopup(): string
    {
        return "Truck: {$this->license_plate}";
    }
}

```

Your fleet management system is now ready. You can track assets, visualize them filtered by category, and see them move in real-time with zero additional frontend configuration.

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance89

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

13

Last Release

56d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/d1f92a7449f5c67538551ce77a35f7c7ff2dc059574879ed8ff566f72e24c47a?d=identicon)[ilbullo](/maintainers/ilbullo)

---

Top Contributors

[![ilbullo](https://avatars.githubusercontent.com/u/1204664?v=4)](https://github.com/ilbullo "ilbullo (15 commits)")

### Embed Badge

![Health badge](/badges/ilbullo-geo-service/health.svg)

```
[![Health](https://phpackages.com/badges/ilbullo-geo-service/health.svg)](https://phpackages.com/packages/ilbullo-geo-service)
```

###  Alternatives

[nasirkhan/laravel-starter

A CMS like modular Laravel starter project.

1.4k2.7k](/packages/nasirkhan-laravel-starter)[ramonrietdijk/livewire-tables

Dynamic tables for models with Laravel Livewire

21355.6k](/packages/ramonrietdijk-livewire-tables)[lakm/laravel-comments

Integrate seamless commenting functionality into your Laravel project.

40614.3k1](/packages/lakm-laravel-comments)[team-nifty-gmbh/tall-datatables

Server-side rendered datatables for Laravel and Livewire

1319.7k3](/packages/team-nifty-gmbh-tall-datatables)[tomshaw/electricgrid

A feature-rich Livewire package designed for projects that require dynamic, interactive data tables.

119.2k](/packages/tomshaw-electricgrid)[marcorieser/statamic-livewire

A Laravel Livewire integration for Statamic.

23100.9k12](/packages/marcorieser-statamic-livewire)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)