README

A NativePHP Mobile v4 plugin for displaying and scheduling local notifications from Laravel. It uses UNUserNotificationCenter on iOS and NotificationManager plus AlarmManager on Android, with no third-party native dependencies.

Features

Request and inspect notification permission
Display immediately or schedule for later
Attach application data and an optional deep-link URL
List pending notifications
Cancel one or all notifications
Configure Android notification channels per notification
Call the same bridge from PHP or JavaScript

Install in a local Laravel application

Add a path repository to the Laravel application's composer.json:

{
    "repositories": [
        { "type": "path", "url": "../nativephp-local-notifications" }
    ]
}

Then install and register it:

composer require phnuestro/nativephp-local-notifications:@dev
php artisan vendor:publish --tag=nativephp-plugins-provider
php artisan native:plugin:register phnuestro/nativephp-local-notifications
php artisan native:plugin:validate
php artisan native:run

Native code is compiled into the app, so changes under resources/android or resources/ios require rebuilding the native app. If the manifest changes significantly, run php artisan native:install --force first.

PHP usage

use NativePhp\LocalNotifications\Facades\LocalNotification;

LocalNotification::requestPermission();

LocalNotification::send(
    title: 'Invoice due',
    body: 'Invoice #42 is due tomorrow.',
    at: now()->addDay(),
    options: [
        'id' => 'invoice-42',
        'data' => ['invoice_id' => 42],
        'url' => 'myapp://invoices/42',
        'sound' => true,
        'badge' => 1,
        'channel_id' => 'billing',
        'channel_name' => 'Billing reminders',
    ],
);

Omit at to show the notification immediately. An integer at value is interpreted as a Unix timestamp in seconds.

$status = LocalNotification::permissionStatus();
$pending = LocalNotification::pending();

LocalNotification::cancel('invoice-42');
LocalNotification::cancelAll();

Publish the optional configuration file to change the default Android channel:

php artisan vendor:publish --tag=local-notifications-config

JavaScript usage

Copy or expose resources/js/localNotifications.js through your app's asset build, then:

import { LocalNotifications } from './localNotifications';

await LocalNotifications.requestPermission();
await LocalNotifications.schedule({
    id: 'invoice-42',
    title: 'Invoice due',
    body: 'Invoice #42 is due tomorrow.',
    at: Date.now() + 86_400_000,
    data: { invoice_id: 42 },
    url: 'myapp://invoices/42',
    sound: true,
    channel_id: 'billing',
    channel_name: 'Billing reminders',
});

Platform notes

Android 13+ asks for POST_NOTIFICATIONS; older Android versions grant notification access at install time.
On Android 13+, the first requestPermission() call returns status: prompted while the system dialog is open. Call permissionStatus() after the user responds when your UI needs the final result.
Android scheduled notifications use setAndAllowWhileIdle, which is battery-friendly but not exact. This avoids the restricted exact-alarm permission.
Android alarms do not survive a device reboot. Reschedule important reminders when the app next starts.
On Android, url is placed on the launch intent and notification data is included as the local_notification_data JSON extra.
On iOS, data and url are placed in the notification's userInfo. Routing a notification tap into Laravel depends on the host application's notification delegate/deep-link setup.
iOS may cap the number of pending local notifications. Avoid scheduling an unbounded queue.

Validation and tests

composer validate --strict
composer install
composer test
php artisan native:plugin:validate

Device-level behavior should be verified on both a physical Android device and iPhone because simulators do not reproduce every permission, battery, and delivery condition.

License

MIT

phnuestro / nativephp-local-notifications

Maintainers

Package info

Statistics

Security