Download the PHP package mayaram/laravel-browser-location without Composer

Laravel Browser Location

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

Run the installer command:

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:

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:

Browser Events

The tracker dispatches these native DOM events on document:

JavaScript API

Configuration

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

Geocoder service (Google / Mapbox / OpenStreetMap)

Configure provider in .env

Usage via facade

Usage via dependency injection (preferred)

Normalized response shape

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

2) Save locations manually (Spatie-style API)

3) Read stored locations

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

Optional explicit locationable models

Livewire integration (v3 & v4)

Basic setup

1. Add the trait to your Livewire component:

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

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:

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:

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:

Compatibility matrix

Framework support

Middleware Validation

The middleware accepts location from:

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

Testing

License

MIT