README

Capture browser-based GPS location in Laravel using the HTML5 Geolocation API.
Works with Laravel 10-13, plain Blade, and Livewire 3 / 4.

Table of Contents

• Core features
• Installation
• Usage: Blade component
  • All Component Props
  • Browser Events
  • JavaScript API
• Configuration
• Geocoder service (Google / Mapbox / OpenStreetMap)
  • Configure provider in .env
  • Usage via facade
  • Usage via dependency injection (preferred)
  • Normalized response shape
  • Best practices
• Location persistence collections
  • 1) Add the HasLocations trait to your model
  • 2) Save locations manually (Spatie-style API)
  • 3) Read stored locations
  • 4) Automatic saving flow (no manual save required)
  • Persistence config
  • Optional explicit locationable models
• Livewire integration (v3 & v4)
  • Basic setup
  • Trait helper methods
  • Livewire 3 & 4 — recommended attributes
  • Livewire 4: using #[On] to react via JS dispatch
• Compatibility matrix
• Middleware Validation
• Testing
• License

Core features

• Accurate GPS capture with HTML5 Geolocation
• Works with plain Blade and Livewire 3 — Livewire is fully optional
• Ready-to-use Blade component (<x-browser-location-tracker />)
• SPA-friendly: re-captures after every Livewire navigation without page reload
• Permission + error handling for denied / timeout / unavailable states
• Accuracy detection (excellent, good, poor, unknown)
• Typed PHP helper methods on the Livewire trait
• Provider-based geocoding + reverse geocoding (Google, Mapbox, OpenStreetMap)
• Cache-ready geocoder responses for fast repeated lookups
• Spatie-style location collections with polymorphic model ownership
• Automatic DB persistence (JS → API → Laravel)
• Auto-loaded migration for browser_locations table
• One-command setup: php artisan browser-location:install
• Middleware alias for route-level location validation (browser-location.validate)

Installation

composer require mayaram/laravel-browser-location

Run the installer command:

php artisan browser-location:install

This publishes config / views / migrations and runs migrations automatically.

Usage: Blade component

Drop the tracker anywhere in any Blade view — including inside a Livewire component:

<x-browser-location-tracker />

Default behaviour: auto-capture="true" and force-permission="true" are on by default, so the browser will request the user's location immediately. Set them to false if you want manual control.

All Component Props

Example with custom options:

<x-browser-location-tracker
    button-text="Locate Me"
    :auto-capture="false"
    :force-permission="false"
    :watch="true"
    :timeout="10000"
    livewire-method="saveLocation"
    :required-accuracy-meters="80"
/>

Browser Events

The tracker dispatches these native DOM events on document:

document.addEventListener("browser-location:updated", (e) => {
    console.log(e.detail.latitude, e.detail.longitude);
});

JavaScript API

// Last-initialized tracker on the page:
window.BrowserLocationTracker.capture(); // Trigger a fresh capture
window.BrowserLocationTracker.requestPermission(); // Alias for capture()
window.BrowserLocationTracker.getJson(); // Returns latest data as JSON string

// Named instance (if you have multiple trackers):
window.BrowserLocation["browser-location-<ulid>"].capture();

Configuration

php artisan vendor:publish --tag=browser-location-config

Creates config/browser-location.php. Key options:

'auto_save'          => false,   // persist every capture automatically
'min_accuracy'       => 200,     // max accepted accuracy in metres
'prevent_duplicates' => true,    // skip saves within 20 m of last point
'default_collection' => 'default',

'component' => [
    'auto_capture'    => true,
    'force_permission' => true,
    'watch'           => false,
    'livewire_method' => 'setBrowserLocation',
],

Geocoder service (Google / Mapbox / OpenStreetMap)

Configure provider in .env

# Provider: google | mapbox | openstreetmap
BROWSER_LOCATION_GEOCODER_PROVIDER=openstreetmap

# Google
BROWSER_LOCATION_GOOGLE_API_KEY=

# Mapbox
BROWSER_LOCATION_MAPBOX_ACCESS_TOKEN=

# OpenStreetMap (required for Nominatim policy compliance)
BROWSER_LOCATION_OSM_USER_AGENT="your-app-name/1.0 (admin@example.com)"
BROWSER_LOCATION_OSM_EMAIL=admin@example.com

# Cache
BROWSER_LOCATION_GEOCODER_CACHE_ENABLED=true
BROWSER_LOCATION_GEOCODER_CACHE_TTL=3600

Usage via facade

use Mayaram\BrowserLocation\Facades\Geocoder;

$reverse = Geocoder::reverse(28.6139, 77.2090);
$forward = Geocoder::forward('New Delhi, India');

Usage via dependency injection (preferred)

use Mayaram\BrowserLocation\Contracts\Geocoder;

class CheckoutController
{
    public function __construct(private readonly Geocoder $geocoder) {}

    public function __invoke(): array
    {
        return $this->geocoder->reverse(28.6139, 77.2090);
    }
}

Normalized response shape

[
    'provider' => 'openstreetmap',
    'query'    => [...],
    'resolved' => [
        'formatted_address' => '...',
        'latitude'          => 28.6139,
        'longitude'         => 77.209,
        'place_id'          => '...',
        'components'        => [...],
    ],
    'results' => [...],
    'raw'     => [...],
]

Best practices

• Prefer dependency injection for testability.
• Keep API credentials in .env — never commit keys.
• Enable cache in production to reduce cost and latency.
• For OpenStreetMap/Nominatim, always supply a real user_agent and contact email.
• Catch Mayaram\BrowserLocation\Exceptions\GeocoderException at your application boundary.

Location persistence collections

1) Add the HasLocations trait to your model

use Mayaram\BrowserLocation\Concerns\HasLocations;

class User extends Authenticatable
{
    use HasLocations;
}

2) Save locations manually (Spatie-style API)

$user->addLocation($data)->toLocationCollection('checkins');
$order->addLocation($data)->toLocationCollection('delivery');
$user->addLocation($data)->toSingleLocationCollection('live');

3) Read stored locations

$latest = $user->getLatestLocation();
$visits = $user->getLocations('visits');

4) Automatic saving flow (no manual save required)

When <x-browser-location-tracker /> captures a location the package:

1. POSTs coordinates to POST /browser-location/capture
2. Validates via browser-location.validate middleware
3. Applies quality checks (accuracy threshold + anti-duplicate rules)
4. Persists in browser_locations and enriches meta with raw GPS, geocoder response, IP, user-agent

Persistence config

'auto_save'          => false,
'min_accuracy'       => 200,
'prevent_duplicates' => true,
'default_collection' => 'default',
'capture_endpoint'   => '/browser-location/capture',

Optional explicit locationable models

// config/browser-location.php
'allowed_locationable_models' => [
    App\Models\Order::class,
],

Livewire integration (v3 & v4)

Basic setup

1. Add the trait to your Livewire component:

<?php

namespace App\Livewire;

use Livewire\Component;
use Mayaram\BrowserLocation\Livewire\Concerns\InteractsWithBrowserLocation;

class TripTracker extends Component
{
    use InteractsWithBrowserLocation;

    public string $status = 'Waiting for location…';

    // Called automatically after every location update
    public function onBrowserLocationUpdated(array $location): void
    {
        $this->status = "Lat: {$this->getLatitude()}, Lng: {$this->getLongitude()}";
    }

    // Optional: return the model that locations should be attached to
    public function getBrowserLocationable(): ?\Illuminate\Database\Eloquent\Model
    {
        return auth()->user();
    }

    public function render()
    {
        return view('livewire.trip-tracker');
    }
}

2. Add the tracker inside the component's Blade view:

{{-- livewire/trip-tracker.blade.php --}}
<div>
    <x-browser-location-tracker />   {{-- wire:ignore is applied automatically --}}

    @if ($this->hasLocation())
        <p>Lat: {{ $this->getLatitude() }}, Lng: {{ $this->getLongitude() }}</p>
        <p>Accuracy: {{ $this->getAccuracy() }} m ({{ $this->getAccuracyLevel() }})</p>
    @endif

    <p>{{ $status }}</p>
</div>

Trait helper methods

All methods are available on any Livewire component that uses InteractsWithBrowserLocation:

Coordinate helpers

Permission & error helpers

Other helpers

Lifecycle hook (onBrowserLocationUpdated)

Implement this method on your component to react every time a new location arrives:

public function onBrowserLocationUpdated(array $location): void
{
    // $location has the same keys as $this->browserLocation
    $this->dispatch('location-saved');
}

Livewire 3 & 4 — recommended attributes

The trait itself does not include #[Locked] or #[On] because Livewire is an optional dependency. Add them directly on your component for the best security and DX:

use Livewire\Attributes\Locked;
use Livewire\Attributes\On;

// Prevents the client from tampering with $browserLocation via wire:model
#[Locked]
public array $browserLocation = [];

// Allows triggering setBrowserLocation via $dispatch('browser-location:updated', payload)
// in addition to the default direct component.call() mechanism
#[On('browser-location:updated')]
public function setBrowserLocation(array $location): void
{
    // Call the trait's implementation:
    $this->persistBrowserLocationIfNeeded($location);
    $this->browserLocation = $location;

    if (method_exists($this, 'onBrowserLocationUpdated')) {
        $this->onBrowserLocationUpdated($location);
    }
}

Both #[Locked] and #[On] work identically in Livewire 3 and Livewire 4.

Livewire 4: using #[On] to react via JS dispatch

An alternative to having JS call setBrowserLocation directly is to dispatch a browser event and let Livewire 4's #[On] handle it:

<x-browser-location-tracker
    livewire-method=""
    event-name="browser-location:updated"
/>

// In your own JS you can also do:
Livewire.dispatch("browser-location:updated", payload);

#[On('browser-location:updated')]
public function setBrowserLocation(array $location): void { ... }

Compatibility matrix

Framework support

Middleware Validation

Route::post('/checkout', CheckoutController::class)
    ->middleware('browser-location.validate');

The middleware accepts location from:

• Request body fields (latitude, longitude, …)
• A location object in the request body
• An X-Browser-Location JSON header

Testing

composer test

License

MIT