README

Want to get a user's location before an Action is performed on Filament?

This Filament plugin adds geolocation capabilities to your Filament Actions, allowing you to easily capture and use a user's geographic location. Also, it's plug and play! 🚀

🎯 Gets real-time user location with browser's Geolocation API
⚡ Halts action execution until location is captured
🔄 Automatically disables other actions while waiting
🛠 Injects location data into before(), action(), and after() methods
🔒 Built-in validation and error handling
📦 Zero configuration required - works out of the box
🎨 Filament-Native Experience

Navigation

Filament Geolocate Me

Installation

You can install the package via composer:

composer require diogogpinto/filament-geolocate-me

Usage

Basic Usage

Import the HasGeolocation trait in the Livewire component where your Filament Action is and add geolocation to any Filament action using the withGeolocation() method:

use Filament\Actions\Action;
use DiogoGPinto\GeolocateMe\Data\Coordinates;

//Import the HasGeolocation trait
use HasGeolocation;

Action::make('checkIn')
    ->withGeolocation()
    ->action(function (Coordinates $coordinates) {
        // Handle the location data in your action
        $latitude = $coordinates->latitude;
        $longitude = $coordinates->longitude;
        $accuracy = $coordinates->accuracy; // in meters, optional
    });
    ->before(function (Coordinates $coordinates) {
        // Do something with location data before running the action
    });
    ->after(function (Coordinates $coordinates) {
        // Do something with location data after running the action
    });

Caution

This plugin only works with custom Filament Actions. It is NOT compatible with Filament's prebuilt actions (like EditAction, CreateAction, etc.)

Tip

Location data (Coordinates) can be accessed in three action phases: before, action and after.

Error Handling

The plugin automatically handles geolocation errors. You can check for errors in your action:

Action::make('checkIn')
    ->withGeolocation()
    ->action(function (Coordinates $coordinates) {
        if ($coordinates->hasError()) {
            // Handle error case
            $errorMessage = $coordinates->error;
            return;
        }
        
        // Process location data
    });

Action Lifecycle

The geolocation process follows this sequence:

Action is triggered and immediately halted
All other actions are temporarily disabled until the location process finishes
Browser requests location permission
Filament waits for location from Alpine
Loading state is shown
Location is captured and the action is fired
Action is executed with location data injected

Coordinates Data Structure

The Coordinates class provides the following properties:

$coordinates->latitude;   // float: -90 to 90
$coordinates->longitude;  // float: -180 to 180
$coordinates->accuracy;   // float|null: accuracy in meters
$coordinates->error;      // string|null: error message if something went wrong

Validation

The plugin automatically validates coordinates to ensure they are within valid ranges:

Latitude: -90 to 90 degrees
Longitude: -180 to 180 degrees

Custom Styling

The plugin uses Filament's default loading indicators. You can customize the appearance through Filament's theming system.

Examples

Basic Check-in System

use DiogoGPinto\GeolocateMe\Data\Coordinates;

Action::make('checkIn')
    ->withGeolocation()
    ->action(function (Coordinates $coordinates) {
        //Handle Error - if you can't locate the user, do nothing
        if ($location->hasError()) {
            Notification::make()
                ->danger()
                ->title('Error retrieving location')
                ->body($location->error)
                ->send();

            return;
        }

        //Create a checkin
        CheckIn::create([
            'latitude' => $coordinates->latitude,
            'longitude' => $coordinates->longitude,
            'accuracy' => $coordinates->accuracy,
            'user_id' => auth()->id(),
        ]);
        
        Notification::make()
            ->success()
            ->title('Checked in successfully')
            ->send();
    });

Requirements

PHP 8.1 or higher
Laravel 10.0 or higher
FilamentPHP 3.0 or higher
Browser with Geolocation API support

Browser Support

This plugin relies on the Geolocation API, which is supported by all modern browsers. Users will need to grant location permissions for the feature to work.

Security

The plugin handles location data on the client side only when explicitly requested through an action. All coordinate validation is performed server-side to ensure data integrity.

Production Usage Warning