Location and local notifications for NativePHP Mobile v4, driven from Laravel. Basho (場所) means "place".
- One-shot position: ask for the "when in use" permission if needed, then get one fix (latitude, longitude, accuracy) as an event.
- Local notifications: schedule a notification at a given time, cancel it, and open a route of the app when it is tapped, even from a cold start.
- Arrival notifications: watch places and post a notification on arriving at one, also when the app is closed (geofencing, "Always" permission).
Status: v0.1, experimental.
| Feature | iOS | Android |
|---|---|---|
Basho.CurrentPosition |
yes (CoreLocation) | yes (LocationManager); the first call without permission shows the system dialog and fails with permission_requested |
Basho.ScheduleNotification, Basho.CancelNotifications |
yes (UNUserNotificationCenter) |
not yet: scheduling fails with unsupported |
Basho.MonitorArrivals |
yes (CoreLocation region monitoring) | not yet: fails with ArrivalsFailed unsupported |
composer require alpine-ronin/nativephp-basho
php artisan native:plugin:register alpine-ronin/nativephp-basho
php artisan native:runFor local development, add a path repository to the app's composer.json:
"repositories": [{ "type": "path", "url": "../nativephp-basho" }]The plugin adds NSLocationWhenInUseUsageDescription and NSLocationAlwaysAndWhenInUseUsageDescription to Info.plist (in English, with a French translation written when the app lists fr in nativephp.supported_locales) and the coarse and fine location permissions to the Android manifest.
use AlpineRonin\NativeBasho\Events\PermissionDenied;
use AlpineRonin\NativeBasho\Events\PositionFailed;
use AlpineRonin\NativeBasho\Events\PositionReceived;
use AlpineRonin\NativeBasho\Facades\Basho;
use Native\Mobile\Attributes\On;
Basho::currentPosition()->id('place-form')->get();
#[On(PositionReceived::class, when: ['id' => 'place-form'])]
public function onPosition(float $latitude, float $longitude, float $accuracy): void
{
// accuracy: horizontal accuracy in metres
}
#[On(PermissionDenied::class, when: ['id' => 'place-form'])]
public function onDenied(): void {}
#[On(PositionFailed::class, when: ['id' => 'place-form'])]
public function onFailed(string $code, string $message): void {}Callbacks can also be attached to the request: ->positionReceived(fn (PositionReceived $fix) => ...), ->positionFailed(...), ->permissionDenied(...).
Basho::notification('note-3')
->title('Kitchen')
->body('Buy milk')
->at(now()->addMinutes(2))
->url('/places/3')
->schedule();
Basho::cancelNotifications(['note-3']);The first schedule() asks for the notification permission. Scheduling again with the same id replaces the notification; cancelling also removes it from the notification centre once delivered. Tapping a notification opens its url as a deep link (Route::native screens included), also when the tap launches the app. Notifications are shown while the app is in the foreground too.
On iOS the plugin becomes the UNUserNotificationCenter delegate at launch (ios.init_function). Another plugin that sets this delegate, such as a push notification plugin, would replace it.
Basho::monitorArrivals([
new Arrival('place-3', latitude: 48.85837, longitude: 2.29448, radius: 100, title: 'Kitchen', body: '2 notes here', url: '/places/3'),
]);Each call replaces the whole list; an empty list stops monitoring. The first non-empty list asks for the Always location permission and the notification permission. Entering a place's circle posts its notification right away, also when the app is closed: iOS relaunches the app in the background and the plugin posts the notification natively, from the list it saved, without PHP. Tapping it opens its url like any other notification.
iOS monitors 20 regions at most per app: the plugin monitors the 20 places nearest to the last known position and refreshes them on significant location changes. Precision is about 100 m, and a radius over maximumRegionMonitoringDistance is clamped. With only "While Using" permission, entries are reported while the app runs, not when it is closed.
For a smaller distance, pass notifyWithin (metres, below radius): new Arrival(..., radius: 100, ..., notifyWithin: 10). Entering the region then starts precise location updates, in the background too (location background mode), and the notification is posted once a fix is within notifyWithin of the place with an accuracy at least as good. Updates stop on the notification, on leaving the region or after 30 minutes. GPS accuracy is often 10 to 50 m indoors, so a 10 m distance may only be reached outdoors.
Every event carries id, the request id.
| Event | Payload |
|---|---|
PositionReceived |
id, latitude, longitude, accuracy (metres) |
PositionFailed |
id, code (unavailable, permission_requested), message |
PermissionDenied |
id |
NotificationTapped |
id, url; dropped when the tap cold-starts the app before PHP is up (the url still opens) |
NotificationFailed |
id, code (permission_denied, unavailable, unsupported), message |
ArrivalsFailed |
code (permission_denied, unavailable, unsupported), message; no id |
Native errors returned synchronously by the bridge are thrown as BashoBridgeException.
./.docker make install
./.docker make ci # lint, Pest, Kotlin compile against stubs, stub drift check
make ios # macOS + Xcode only, or the `ios` CI jobMIT