smronju / nativephp-geolocation

1.0.0 2026-11-08 18:53 UTC

Requires

• php: ^8.2
• nativephp/mobile: ^4.1

Requires (Dev)

• pestphp/pest: ^3.0 || ^5.0

MIT

• Mohammad Shoriful Islam Ronju

• geolocation
• mobile
• laravel
• location
• android
• gps
• ios
• nativephp

Published on Packagist.org on 2026-11-08 18:54 UTC

README

Implements NativePHP Mobile's Geolocation on Android and iOS. nativephp/mobile v4 ships the PHP side (Native\Mobile\Facades\Geolocation, PendingGeolocation, the Geolocation\* events) but registers its bridge functions on neither platform. This plugin registers them; it adds no PHP API of its own.

Bridge function	Android	iOS
Geolocation.GetCurrentPosition	Fused Location Provider; LocationManager on phones without Google Play services	Core Location requestLocation()
Geolocation.CheckPermissions	checkSelfPermission	authorizationStatus
Geolocation.RequestPermissions	system permission prompt	requestWhenInUseAuthorization()

watchPosition() and the background-watch calls are not implemented.

Use

use Native\Mobile\Attributes\On;
use Native\Mobile\Events\Geolocation\LocationReceived;
use Native\Mobile\Facades\Geolocation;

$request = Geolocation::getCurrentPosition(fineAccuracy: true);
$this->gpsRequest = $request->getId();
$request->get();

#[On(LocationReceived::class)]
public function located(bool $success, ?float $latitude = null, ?float $longitude = null, ?float $accuracy = null, ?string $error = null, ?string $id = null): void
{
    if ($id !== $this->gpsRequest) {
        return;
    }
    // ...
}

Check that the plugin is in the build with nativephp_can('Geolocation.GetCurrentPosition').

Behaviour

• Returns at once; the answer is the event PendingGeolocation named, with the caller's id.
• Asks for location permission the first time it's needed, then carries on.
• A fix up to 30 seconds old is reused; otherwise it waits up to 30 seconds.
• fineAccuracy: true asks for GPS-level accuracy (needs the precise-location grant on Android 12+ and iOS 14+; with approximate only, it answers coarsely).
• On failure, LocationReceived has success: false and error set to one of permission_denied, location_disabled, timeout or unavailable, so the app can show its own (translated) message.
• Permission events report granted, denied, or prompt (iOS, not asked yet). Android reports denied until granted, since it can usually ask again.

Manifest

• Android: ACCESS_FINE_LOCATION, ACCESS_COARSE_LOCATION; com.google.android.gms:play-services-location:21.3.0; API 26+.
• iOS: NSLocationWhenInUseUsageDescription; iOS 15+.

Install

Add it to composer.json and list GeolocationServiceProvider in the app's NativeServiceProvider::plugins() (php artisan native:plugin:register). php artisan native:plugin:validate checks the manifest.

Tests

tests/PluginTest.php checks the manifest and sources against the contract core calls. In the ARKO repo it runs as part of mobile/'s Pest suite.