Push Notifications Plugin for NativePHP Mobile#

Push notifications via Firebase Cloud Messaging (FCM) for NativePHP Mobile apps. Handles device registration, token management, permission flow, deep linking from notifications, data-only messages with background processing, and server-side sending.

Works on iOS (APNs via FCM) and Android (FCM).

Installation#

Copied!

composer require nativephp/mobile-firebase

composer require nativephp/mobile-firebase

Firebase Setup#

Android#

Create a Firebase project at Firebase Console
Add your Android app (use your app's package name)
Download google-services.json and place it in your project root
The plugin compiler copies it to the Android build automatically

iOS#

In the same Firebase project, add your iOS app
Download GoogleService-Info.plist and place it in your project root
Enable Push Notifications capability in your Apple Developer account
Upload your APNs key to Firebase Console > Project Settings > Cloud Messaging
The plugin compiler handles Xcode configuration automatically

Server-Side#

To send push notifications from your server, you need a Firebase service account:

Firebase Console > Project Settings > Service Accounts
Click "Generate new private key"
Save the JSON file and set the path in your .env:

Copied!

FIREBASE_CREDENTIALS=/path/to/service-account.json

FIREBASE_CREDENTIALS=/path/to/service-account.json

Quick Start#

Copied!

use Native\Mobile\Facades\PushNotifications;
 
// 1. Check current permission status
$status = PushNotifications::checkPermission();
 
// 2. Enroll for push notifications (prompts user if needed)
PushNotifications::enroll();
 
// 3. Handle the token when it arrives

use Native\Mobile\Facades\PushNotifications;

// 1. Check current permission status
$status = PushNotifications::checkPermission();

// 2. Enroll for push notifications (prompts user if needed)
PushNotifications::enroll();

// 3. Handle the token when it arrives

Copied!

use Native\Mobile\Attributes\OnNative;
use Native\Mobile\Events\PushNotification\TokenGenerated;
 
#[OnNative(TokenGenerated::class)]
public function handleToken(string $token)
{
    // Send token to your server and store it for this user
    $this->user->update(['push_token' => $token]);
}

use Native\Mobile\Attributes\OnNative;
use Native\Mobile\Events\PushNotification\TokenGenerated;

#[OnNative(TokenGenerated::class)]
public function handleToken(string $token)
{
    // Send token to your server and store it for this user
    $this->user->update(['push_token' => $token]);
}

Permission Flow#

Checking Permission#

Always check before prompting. This does not trigger a system dialog.

Copied!

$status = PushNotifications::checkPermission();
// Returns: "granted", "denied", "not_determined", "provisional", or "ephemeral"

$status = PushNotifications::checkPermission();
// Returns: "granted", "denied", "not_determined", "provisional", or "ephemeral"

Status	Description
`granted`	User allowed notifications
`denied`	User denied — direct them to system Settings
`not_determined`	Never asked — safe to call `enroll()`
`provisional`	Quiet notifications allowed (iOS only)
`ephemeral`	App Clips only (iOS)

Enrolling#

Requests permission (if not_determined) and registers for push notifications. On success, a TokenGenerated event fires with the device token.

Copied!

PushNotifications::enroll();

PushNotifications::enroll();

If permission is already granted, calling enroll() skips the dialog and immediately fetches the token.

Getting the Token#

Retrieve the cached token at any time:

Copied!

$token = PushNotifications::getToken();

$token = PushNotifications::getToken();

Returns the FCM token on Android, APNs/FCM token on iOS, or null if not yet enrolled.

Events#

TokenGenerated#

Fired when a push token is available after enrollment.

PHP (Livewire)

Copied!

use Native\Mobile\Attributes\OnNative;
use Native\Mobile\Events\PushNotification\TokenGenerated;
 
#[OnNative(TokenGenerated::class)]
public function handleToken(string $token)
{
    // Store token on your server for this user/device
    $this->user->update(['push_token' => $token]);
}

use Native\Mobile\Attributes\OnNative;
use Native\Mobile\Events\PushNotification\TokenGenerated;

#[OnNative(TokenGenerated::class)]
public function handleToken(string $token)
{
    // Store token on your server for this user/device
    $this->user->update(['push_token' => $token]);
}

JavaScript (Vue)

Copied!

import { On, Off, Events } from '#nativephp';
import { onMounted, onUnmounted } from 'vue';
 
const handleToken = ({ token }) => {
    // Send to your backend
    fetch('/api/push-token', {
        method: 'POST',
        body: JSON.stringify({ token }),
    });
};
 
onMounted(() => On(Events.PushNotification.TokenGenerated, handleToken));
onUnmounted(() => Off(Events.PushNotification.TokenGenerated, handleToken));

import { On, Off, Events } from '#nativephp';
import { onMounted, onUnmounted } from 'vue';

const handleToken = ({ token }) => {
    // Send to your backend
    fetch('/api/push-token', {
        method: 'POST',
        body: JSON.stringify({ token }),
    });
};

onMounted(() => On(Events.PushNotification.TokenGenerated, handleToken));
onUnmounted(() => Off(Events.PushNotification.TokenGenerated, handleToken));

JavaScript (React)

Copied!

import { On, Off, Events } from '#nativephp';
import { useEffect } from 'react';
 
useEffect(() => {
    const handler = On(Events.PushNotification.TokenGenerated, ({ token }) => {
        sendTokenToServer(token);
    });
    return () => Off(Events.PushNotification.TokenGenerated, handler);
}, []);

import { On, Off, Events } from '#nativephp';
import { useEffect } from 'react';

useEffect(() => {
    const handler = On(Events.PushNotification.TokenGenerated, ({ token }) => {
        sendTokenToServer(token);
    });
    return () => Off(Events.PushNotification.TokenGenerated, handler);
}, []);

PushNotificationReceived (and custom events)#

This event does not fire for every push. Regular notifications (those with a notification block — title/body that the OS draws into the system tray) do not dispatch any PHP event. The native handlers only dispatch a PHP event when the FCM payload is a data message and the data contains an event key naming the FQCN of the event class to dispatch.

In other words, PushNotificationReceived is just one possible event class — you opt in by sending its FQCN in the event data key. You can also send any custom event class of your own (e.g. App\Events\SyncNeeded); whatever class name you put in the event key is what gets dispatched.

When a qualifying data message arrives, the plugin boots an ephemeral PHP runtime on the device and dispatches the named event, so any standard Laravel listener will fire — including when the app is backgrounded or killed.

Triggering `PushNotificationReceived`

Send a data-only message with the event FQCN:

Copied!

php artisan fcm:send {token} --data-only \
  --d event="Native\\Mobile\\Events\\PushNotification\\PushNotificationReceived" \
  --d payload='{"foo":"bar"}'

php artisan fcm:send {token} --data-only \
  --d event="Native\\Mobile\\Events\\PushNotification\\PushNotificationReceived" \
  --d payload='{"foo":"bar"}'

Or via the FCM v1 API:

Copied!

{
    "message": {
        "token": "device-token",
        "data": {
            "event": "Native\\Mobile\\Events\\PushNotification\\PushNotificationReceived",
            "payload": "{\"foo\":\"bar\"}"
        },
        "apns": {
            "payload": { "aps": { "content-available": 1 } }
        }
    }
}

{
    "message": {
        "token": "device-token",
        "data": {
            "event": "Native\\Mobile\\Events\\PushNotification\\PushNotificationReceived",
            "payload": "{\"foo\":\"bar\"}"
        },
        "apns": {
            "payload": { "aps": { "content-available": 1 } }
        }
    }
}

Important: #[OnNative] is a Livewire attribute. It only fires when the app is foregrounded and that Livewire component is currently mounted. For background data messages, register a regular Laravel listener instead.

Background-safe (Laravel listener)

Copied!

use Illuminate\Support\Facades\Event;
use Native\Mobile\Events\PushNotification\PushNotificationReceived;
 
// In a service provider's boot()
Event::listen(function (PushNotificationReceived $event) {
    // Runs in the ephemeral PHP runtime — works even when app is backgrounded.
    // Persist data, queue work, update local SQLite, etc.
});

use Illuminate\Support\Facades\Event;
use Native\Mobile\Events\PushNotification\PushNotificationReceived;

// In a service provider's boot()
Event::listen(function (PushNotificationReceived $event) {
    // Runs in the ephemeral PHP runtime — works even when app is backgrounded.
    // Persist data, queue work, update local SQLite, etc.
});

You can also register the listener via EventServiceProvider's $listen array, or as a class-based listener — anything Laravel auto-discovers will work.

Foreground only (Livewire)

If you only need to react while a specific component is on screen:

Copied!

use Native\Mobile\Attributes\OnNative;
use Native\Mobile\Events\PushNotification\PushNotificationReceived;
 
#[OnNative(PushNotificationReceived::class)]
public function handlePush($data)
{
    // Only runs when this Livewire component is mounted in the foreground.
}

use Native\Mobile\Attributes\OnNative;
use Native\Mobile\Events\PushNotification\PushNotificationReceived;

#[OnNative(PushNotificationReceived::class)]
public function handlePush($data)
{
    // Only runs when this Livewire component is mounted in the foreground.
}

What about regular notifications?

If you send a push with a notification block (title/body shown in the tray), the OS handles the display and no PHP event fires — not on tap, not on receipt. To run PHP code when a push arrives, send a data message with an event key as shown above. To navigate somewhere on tap, see Deep Linking.

Sending Notifications#

Test Command#

Send a test notification from your terminal:

Copied!

# Basic notification
php artisan fcm:send {token} --title="Hello" --body="World"
 
# With deep link
php artisan fcm:send {token} --title="New Order" --body="Order #123 ready" --url="/orders/123"
 
# Data-only (silent, triggers background processing)
php artisan fcm:send {token} --data-only --d event=App\\Events\\SyncNeeded --d payload='{"sync_id":42}'
 
# With badge count
php artisan fcm:send {token} --title="Messages" --body="3 unread" --badge=3
 
# Custom data pairs
php artisan fcm:send {token} --title="Update" --d type=order --d order_id=55

# Basic notification
php artisan fcm:send {token} --title="Hello" --body="World"

# With deep link
php artisan fcm:send {token} --title="New Order" --body="Order #123 ready" --url="/orders/123"

# Data-only (silent, triggers background processing)
php artisan fcm:send {token} --data-only --d event=App\\Events\\SyncNeeded --d payload='{"sync_id":42}'

# With badge count
php artisan fcm:send {token} --title="Messages" --body="3 unread" --badge=3

# Custom data pairs
php artisan fcm:send {token} --title="Update" --d type=order --d order_id=55

Sending from PHP#

Use the FCM v1 API with your service account credentials:

Copied!

use Illuminate\Support\Facades\Http;
 
$response = Http::withToken($accessToken)
    ->post("https://fcm.googleapis.com/v1/projects/{$projectId}/messages:send", [
        'message' => [
            'token' => $deviceToken,
            'notification' => [
                'title' => 'Order Shipped',
                'body' => 'Your order is on the way!',
            ],
            'data' => [
                'url' => '/orders/123',
            ],
        ],
    ]);

use Illuminate\Support\Facades\Http;

$response = Http::withToken($accessToken)
    ->post("https://fcm.googleapis.com/v1/projects/{$projectId}/messages:send", [
        'message' => [
            'token' => $deviceToken,
            'notification' => [
                'title' => 'Order Shipped',
                'body' => 'Your order is on the way!',
            ],
            'data' => [
                'url' => '/orders/123',
            ],
        ],
    ]);

Deep Linking#

Push notifications can navigate users to specific screens when tapped. Include a url or link key in the data payload:

Copied!

{
    "message": {
        "token": "device-token",
        "notification": {
            "title": "New Message",
            "body": "You have a new message"
        },
        "data": {
            "url": "/messages/42"
        }
    }
}

{
    "message": {
        "token": "device-token",
        "notification": {
            "title": "New Message",
            "body": "You have a new message"
        },
        "data": {
            "url": "/messages/42"
        }
    }
}

The app navigates to the URL on tap, even from a cold start.

Data Messages (Background Processing)#

Send data-only messages to trigger Laravel event processing on the device without showing a visible notification. The event key in the data payload is required — its value is the FQCN of the event class the plugin dispatches. Without it, no PHP event fires. Use any class — your own (App\Events\…) or the built-in Native\Mobile\Events\PushNotification\PushNotificationReceived:

Copied!

{
    "message": {
        "token": "device-token",
        "data": {
            "event": "App\\Events\\DataSyncRequested",
            "payload": "{\"sync_id\": 42}"
        },
        "apns": {
            "payload": {
                "aps": {
                    "content-available": 1
                }
            }
        }
    }
}

{
    "message": {
        "token": "device-token",
        "data": {
            "event": "App\\Events\\DataSyncRequested",
            "payload": "{\"sync_id\": 42}"
        },
        "apns": {
            "payload": {
                "aps": {
                    "content-available": 1
                }
            }
        }
    }
}

The plugin spins up an ephemeral PHP runtime on the device to dispatch the event, even when the app is in the background. Your Laravel event listeners run natively on the device.

JavaScript API#

Copied!

import { PushNotifications, On, Events } from '#nativephp';
 
// Check permission
const { status } = await PushNotifications.checkPermission();
 
// Enroll (prompts if not_determined)
if (status === 'not_determined') {
    await PushNotifications.enroll();
}
 
// Get cached token
const { token } = await PushNotifications.getToken();
 
// Clear badge
await PushNotifications.clearBadge();
 
// Listen for token
On(Events.PushNotification.TokenGenerated, ({ token }) => {
    console.log('Token:', token);
});

import { PushNotifications, On, Events } from '#nativephp';

// Check permission
const { status } = await PushNotifications.checkPermission();

// Enroll (prompts if not_determined)
if (status === 'not_determined') {
    await PushNotifications.enroll();
}

// Get cached token
const { token } = await PushNotifications.getToken();

// Clear badge
await PushNotifications.clearBadge();

// Listen for token
On(Events.PushNotification.TokenGenerated, ({ token }) => {
    console.log('Token:', token);
});

Recommended Permission Flow#

Don't call enroll() immediately on app launch. Show a pre-prompt first:

Call checkPermission() to get current status
If not_determined, show a custom UI explaining why notifications are valuable
User taps "Enable" — call enroll()
System dialog appears
If granted, TokenGenerated fires
Send token to your server
If denied, show a message directing users to Settings

Copied!

public function requestPush()
{
    $status = PushNotifications::checkPermission();
 
    if ($status === 'denied') {
        Dialog::toast('Enable notifications in Settings');
        return;
    }
 
    PushNotifications::enroll();
}

public function requestPush()
{
    $status = PushNotifications::checkPermission();

    if ($status === 'denied') {
        Dialog::toast('Enable notifications in Settings');
        return;
    }

    PushNotifications::enroll();
}

Platform Notes#

Feature	iOS	Android
Permission prompt	System dialog via UNUserNotificationCenter	System dialog on API 33+ (auto-granted below)
Token type	APNs token → FCM token (if Firebase configured)	FCM token
Background data messages	Ephemeral PHP runtime	Ephemeral PHP runtime
Deep linking	Via `url` or `link` in data payload	Via `url` or `link` in data payload
Badge	Set via APNs payload	OS-managed badge dots
`clearBadge()`	Resets to zero	Cancels all displayed notifications
Firebase config	`GoogleService-Info.plist` in project root	`google-services.json` in project root

Coexistence with Local Notifications#

This plugin works alongside nativephp/mobile-local-notifications. On iOS, the local notifications plugin chains its delegate to this plugin's delegate automatically — both receive their respective callbacks without conflict.

Testing#

This plugin is event- and command-driven, so you test it with Laravel's own fakes — no native bridge or FakeBridge helpers are involved. The three surfaces to exercise are the PushNotificationReceived event, the native:dispatch-push-event command, and the fcm:send command.

Faking and asserting the push event#

The device dispatches PushNotificationReceived (or any event class you name in the payload) when a data message arrives. In a test, fake it and assert on its public $data array:

Copied!

use Illuminate\Support\Facades\Event;
use Native\Mobile\Events\PushNotification\PushNotificationReceived;
 
it('reacts to a received push', function () {
    Event::fake([PushNotificationReceived::class]);
 
    // ... run the code that handles the push ...
    event(new PushNotificationReceived(['title' => 'Hi', 'body' => 'There']));
 
    Event::assertDispatched(
        PushNotificationReceived::class,
        fn (PushNotificationReceived $e) => $e->data === ['title' => 'Hi', 'body' => 'There'],
    );
});

use Illuminate\Support\Facades\Event;
use Native\Mobile\Events\PushNotification\PushNotificationReceived;

it('reacts to a received push', function () {
    Event::fake([PushNotificationReceived::class]);

    // ... run the code that handles the push ...
    event(new PushNotificationReceived(['title' => 'Hi', 'body' => 'There']));

    Event::assertDispatched(
        PushNotificationReceived::class,
        fn (PushNotificationReceived $e) => $e->data === ['title' => 'Hi', 'body' => 'There'],
    );
});

Driving the dispatch command#

On-device, the native handler invokes native:dispatch-push-event to fire the event inside an ephemeral PHP runtime. The command takes two options — --event (the fully-qualified event class) and --payload (a JSON object) — both base64-encoded. It base64-decodes them, json_decodes the payload to an associative array, and dispatches new $eventClass(...$payload) using the array keys as named constructor arguments. So for PushNotificationReceived (whose constructor is public array $data = []), the payload must be keyed on data:

Copied!

use Illuminate\Support\Facades\Event;
use Native\Mobile\Events\PushNotification\PushNotificationReceived;
 
it('dispatches the event from the command', function () {
    Event::fake([PushNotificationReceived::class]);
 
    $this->artisan('native:dispatch-push-event', [
        '--event' => base64_encode(PushNotificationReceived::class),
        '--payload' => base64_encode(json_encode(['data' => ['id' => 42]])),
    ])->assertExitCode(0);
 
    Event::assertDispatched(
        PushNotificationReceived::class,
        fn (PushNotificationReceived $e) => $e->data === ['id' => 42],
    );
});

use Illuminate\Support\Facades\Event;
use Native\Mobile\Events\PushNotification\PushNotificationReceived;

it('dispatches the event from the command', function () {
    Event::fake([PushNotificationReceived::class]);

    $this->artisan('native:dispatch-push-event', [
        '--event' => base64_encode(PushNotificationReceived::class),
        '--payload' => base64_encode(json_encode(['data' => ['id' => 42]])),
    ])->assertExitCode(0);

    Event::assertDispatched(
        PushNotificationReceived::class,
        fn (PushNotificationReceived $e) => $e->data === ['id' => 42],
    );
});

If the named class doesn't exist the command prints an error and dispatches nothing (it still exits 0, since handle() returns void). A blank or invalid payload decodes to [], so the event constructs with its default empty $data.

Testing `fcm:send` without hitting Google#

fcm:send (the SendFcmTest command) is server-side: it reads a Firebase service-account JSON (path from config('services.firebase.credentials'), falling back to the FIREBASE_CREDENTIALS env var), RS256-signs a JWT to mint a Google OAuth2 token, then POSTs a v1 message to the FCM endpoint. Its credential-validation branches (missing / non-existent credentials file) run with no network at all. To exercise the message-assembly and HTTP contract, fake both endpoints with Http::fake():

Copied!

use Illuminate\Support\Facades\Http;
 
Http::fake([
    'oauth2.googleapis.com/*' => Http::response(['access_token' => 'ya29.fake'], 200),
    'fcm.googleapis.com/*' => Http::response(['name' => 'projects/p/messages/0:1'], 200),
]);
 
$this->artisan('fcm:send', ['token' => 'DEVICE_TOKEN'])->assertExitCode(0);
 
Http::assertSent(fn ($request) => str_contains($request->url(), 'fcm.googleapis.com')
    && $request['message']['token'] === 'DEVICE_TOKEN');

use Illuminate\Support\Facades\Http;

Http::fake([
    'oauth2.googleapis.com/*' => Http::response(['access_token' => 'ya29.fake'], 200),
    'fcm.googleapis.com/*' => Http::response(['name' => 'projects/p/messages/0:1'], 200),
]);

$this->artisan('fcm:send', ['token' => 'DEVICE_TOKEN'])->assertExitCode(0);

Http::assertSent(fn ($request) => str_contains($request->url(), 'fcm.googleapis.com')
    && $request['message']['token'] === 'DEVICE_TOKEN');

The OAuth token endpoint's host comes from the service account's token_uri, so match your fake to whatever that JSON declares. Signing the JWT needs a real RSA key via OpenSSL — generate a throwaway service account in the test rather than committing credentials. Live FCM delivery is out of scope for unit tests: it requires a real Firebase service account and network access, so keep it to an integration test against an actual project.

Push Notifications Plugin for NativePHP Mobile#

Installation#

Firebase Setup#

Android#

iOS#

Server-Side#

Quick Start#

Permission Flow#

Checking Permission#

Enrolling#

Getting the Token#

Events#

TokenGenerated#

PHP (Livewire)

JavaScript (Vue)

JavaScript (React)

PushNotificationReceived (and custom events)#

Triggering PushNotificationReceived

Background-safe (Laravel listener)

Foreground only (Livewire)

What about regular notifications?

Sending Notifications#

Test Command#

Sending from PHP#

Deep Linking#

Data Messages (Background Processing)#

JavaScript API#

Recommended Permission Flow#

Platform Notes#

Coexistence with Local Notifications#

Testing#

Faking and asserting the push event#

Driving the dispatch command#

Testing fcm:send without hitting Google#

Triggering `PushNotificationReceived`

Testing `fcm:send` without hitting Google#