Plugin Marketplace

nativephp/mobile-geolocation

Geolocation plugin for NativePHP Mobile - GPS location and permission handling

#Geolocation Plugin for NativePHP Mobile

GPS location and permission handling for NativePHP Mobile applications.

#Overview

The Geolocation API provides access to the device's GPS and location services to determine the user's current position.

#Installation

Copied!
composer require nativephp/mobile-geolocation

#Usage

#PHP (Livewire/Blade)

Copied!
use Native\Mobile\Facades\Geolocation;
 
// Get location using network positioning (faster, less accurate)
Geolocation::getCurrentPosition();
 
// Get location using GPS (slower, more accurate)
Geolocation::getCurrentPosition(true);
 
// Check permission status
Geolocation::checkPermissions();
 
// Request permissions
Geolocation::requestPermissions();

#JavaScript (Vue/React/Inertia)

Copied!
import { geolocation, on, off, Events } from '#nativephp';
 
// Get location using network positioning
await geolocation.getCurrentPosition();
 
// Get location using GPS (high accuracy)
await geolocation.getCurrentPosition()
    .fineAccuracy(true);
 
// With identifier for tracking
await geolocation.getCurrentPosition()
    .fineAccuracy(true)
    .id('current-loc');
 
// Check permissions
await geolocation.checkPermissions();
 
// Request permissions
await geolocation.requestPermissions();

#Events

#LocationReceived

Fired when location data is requested (success or failure).

Event Parameters:

  • bool $success - Whether location was successfully retrieved
  • float $latitude - Latitude coordinate (when successful)
  • float $longitude - Longitude coordinate (when successful)
  • float $accuracy - Accuracy in meters (when successful)
  • int $timestamp - Unix timestamp of location fix
  • string $provider - Location provider used (GPS, network, etc.)
  • string $error - Error message (when unsuccessful)

PHP

Copied!
use Native\Mobile\Attributes\OnNative;
use Native\Mobile\Events\Geolocation\LocationReceived;
 
#[OnNative(LocationReceived::class)]
public function handleLocationReceived(
    $success = null,
    $latitude = null,
    $longitude = null,
    $accuracy = null,
    $timestamp = null,
    $provider = null,
    $error = null
) {
    if ($success) {
        // Use location data
    }
}

Vue

Copied!
import { on, off, Events } from '#nativephp';
import { ref, onMounted, onUnmounted } from 'vue';
 
const location = ref({ latitude: null, longitude: null });
const error = ref('');
 
const handleLocationReceived = (payload) => {
    if (payload.success) {
        location.value = {
            latitude: payload.latitude,
            longitude: payload.longitude
        };
    } else {
        error.value = payload.error;
    }
};
 
onMounted(() => {
    on(Events.Geolocation.LocationReceived, handleLocationReceived);
});
 
onUnmounted(() => {
    off(Events.Geolocation.LocationReceived, handleLocationReceived);
});

#PermissionStatusReceived

Fired when permission status is checked.

Permission Values:

  • 'granted' - Permission is granted
  • 'denied' - Permission is denied
  • 'not_determined' - Permission not yet requested

#PermissionRequestResult

Fired when a permission request completes.

Special Values:

  • 'permanently_denied' - User has permanently denied permission

#Privacy Considerations

  • Explain why you need location access before requesting
  • Request at the right time - when the feature is actually needed
  • Respect denials - provide alternative functionality when possible
  • Use appropriate accuracy - don't request fine location if coarse is sufficient
  • Limit frequency - don't request location updates constantly

#Performance Considerations

  • Battery Usage - GPS uses more battery than network location
  • Time to Fix - GPS takes longer for initial position
  • Indoor Accuracy - GPS may not work well indoors
  • Caching - Consider caching recent locations for better UX

#License

MIT