Debug and Test Laravel FCM Push Notifications with Pushbox

Serhii Andriichuk — Tue, 03 Nov 2026 18:58:06 +0000

You create a push notification in Laravel, send it through Firebase Cloud Messaging (FCM), and... nothing appears on your phone.

What went wrong?

Is the notification payload correct?
Is Firebase configured properly?
Is the device token valid?
Did FCM accept the message?
Is the problem with the notification content or delivery?

Debugging these issues can take time, especially when you need to change code, trigger the notification again, and check the result.

I built Pushbox, an open-source Laravel package that helps you test FCM sending and preview push notifications from a visual interface.

What is Pushbox?

Pushbox is a notification testing and debugging tool for Laravel.

Its two main features are:

Test sending — send a notification directly to a real device through FCM and check the sending result.
Notification preview — inspect the generated notification content and FCM data payload without sending anything.

It also supports notification variants, translations, and different recipients.

The screenshots use an order-shipped notification from a demo store. The setup below uses WelcomePush to keep the code example small.

1. Install Pushbox

Pushbox supports Laravel 12/13 and PHP 8.4/8.5.

Install the package:

composer require andriichuk/pushbox
php artisan pushbox:install

For FCM support, install the Laravel notification channel:

composer require laravel-notification-channels/fcm:^6.2

Open /pushbox in your browser.

2. Register a notification

Let's create a simple FCM notification.

php artisan make:notification WelcomePush

use Illuminate\Notifications\Notification;
use NotificationChannels\Fcm\FcmChannel;
use NotificationChannels\Fcm\FcmMessage;
use NotificationChannels\Fcm\Resources\Notification as FcmNotification;

class WelcomePush extends Notification
{
    public function via(object $notifiable): array
    {
        return [FcmChannel::class];
    }

    public function toFcm(object $notifiable): FcmMessage
    {
        return new FcmMessage(
            notification: new FcmNotification(
                title: 'Welcome!',
                body: 'Hello '.($notifiable->name ?? 'developer').'!',
            ),
            data: [
                'screen' => 'welcome',
            ],
        );
    }
}

Now register it in routes/pushbox.php:

use App\Notifications\WelcomePush;
use Andriichuk\Pushbox\Facades\Pushbox;

Pushbox::add(WelcomePush::class);

Your notification is now available in Pushbox.

You can select it from the interface, inspect its content, and test sending it.

3. Send a test push notification to your device

This is especially useful when your notification is not arriving and you want to check whether the FCM sending request works.

First, configure Firebase credentials using the Laravel FCM notification channel.

Enable test sending in your .env:

PUSHBOX_ALLOW_SEND=true

You can optionally configure a default device token:

PUSHBOX_FCM_TOKEN=your-device-token

Or enter your FCM token directly in the Pushbox interface under Device settings.

Make sure the token belongs to the same Firebase project as your credentials.

For the failure example below, I’m deliberately using an invalid demo token. Use your own device’s FCM token when testing delivery.

Now:

Open /pushbox.
Select your notification.
Check the generated payload.
Click Send notification.
Check the sending result and your device.

Pushbox sends the notification immediately through FCM.

The result can be:

Status	Meaning
Accepted	FCM accepted the sending request
Failed	The sending request failed
Skipped	The notification wasn't sent

Important: An accepted result does not guarantee that the notification was delivered or displayed on the device.

But it helps narrow down the problem.

If sending fails, you can investigate your Firebase configuration, credentials, device token, or message. If FCM accepts the request but nothing appears on the phone, you'll need to investigate device-side delivery and handling.

Inspect a failed send

Here’s Firebase rejecting the invalid demo token. Pushbox displays the failure in the workspace and provides a shortcut back to Device settings.

Expand Technical details to inspect the status, masked target, notification class, FCM channel, and the provider’s error response. Here, Firebase reports that the registration token is invalid.

You can test the notification without triggering the normal application flow every time.

4. Preview the notification payload before sending

Sometimes the problem isn't Firebase.

The notification itself may contain an incorrect title, body, translation, or data payload.

For example:

public function toFcm(object $notifiable): FcmMessage
{
    return new FcmMessage(
        notification: new FcmNotification(
            title: 'Your order is ready',
            body: 'Order #1234 is ready for pickup.',
        ),
        data: [
            'screen' => 'orders',
            'order_id' => '1234',
        ],
    );
}

Pushbox lets you inspect the generated notification and its data fields before sending it.

You can check:

Notification title and body
FCM data payload
Values generated for a specific recipient
Different notification variants

Expand Raw payload to inspect the serialized FCM message. Platform settings shows values such as Android’s time to live.

This is useful when debugging notifications that open the wrong screen, display incorrect text, or contain missing data.

You don't need a physical device just to inspect the payload.

5. Test notifications with different recipients

Notification content often depends on the user.

For example:

body: 'Hello '.($notifiable->name ?? 'developer').'!',

To preview a notification with a specific recipient:

use App\Models\User;
use App\Notifications\WelcomePush;
use Andriichuk\Pushbox\Facades\Pushbox;

Pushbox::to(
    User::factory()->make([
        'name' => 'Ada',
    ])
)->add(WelcomePush::class);

Now you can inspect the notification generated for Ada.

Using factory()->make() avoids creating an actual user record.

This makes it easier to reproduce different notification scenarios during development.

6. Compare notification variants

Sometimes you need to test multiple versions of a notification.

Pushbox lets you organize notifications into categories and register named variants.

Pushbox::to(
    User::factory()->make(['name' => 'Ada'])
)
    ->category('Onboarding')
    ->group(function () {
        Pushbox::add(WelcomePush::class)
            ->variant(
                'Another greeting',
                fn (): WelcomePush => new WelcomePush()
            );
    });

This example registers a named variant. You can return a differently configured notification instance to compare actual content changes.

It's useful when working with different notification messages or testing alternative payloads.

In the demo, the Long order reference variant provides a longer title and body to check text wrapping.

Check collapsed and expanded previews

Switch between Collapsed and Expanded to check how much text fits. Long titles and bodies can be truncated in the collapsed preview. The Android preview is an approximation; actual rendering depends on the device and client app.

7. Preview notifications in different languages

If your application supports multiple languages, you probably need to check how push notifications look for each locale.

For example:

new FcmNotification(
    title: __('notifications.welcome_title'),
    body: __('notifications.welcome_body'),
);

Pushbox supports a locale selector.

Publish the configuration:

php artisan vendor:publish --tag=pushbox-config

Configure available languages:

// config/pushbox.php

'locales' => [
    'en' => 'English',
    'uk' => 'Ukrainian',
],

Now you can switch between languages in the interface and inspect the generated notification.

This helps catch missing or incorrect translations before sending them to users.

8. Restrict access

Pushbox is a developer tool, so don't leave it publicly accessible.

You can disable it:

PUSHBOX_ENABLED=false

Or protect it using a Laravel Gate:

use Illuminate\Support\Facades\Gate;

Gate::define('viewPushbox', function (?User $user): bool {
    return $user !== null
        && $user->can('use-developer-tools');
});

Pushbox also supports middleware and IP allowlists.

Configure access restrictions before using it in a publicly accessible environment.

Final thoughts

Debugging push notifications shouldn't require repeatedly triggering your application's normal notification flow just to check a payload or test FCM sending.

With Pushbox, you can:

Send test notifications directly to a real device.
Check whether FCM accepted or rejected a sending request.
Preview notification content and payloads before sending.
Test different recipients, variants, and translations.

It's not a replacement for Firebase delivery diagnostics, but it makes the Laravel side of push notification debugging easier.

GitHub: https://github.com/andriichuk/pushbox

Pushbox is open-source and MIT-licensed.

I'd love to hear how other Laravel developers debug push notification issues.

How do you currently test FCM sending and inspect notification payloads in your projects?

DEV Community: Serhii Andriichuk

Debug and Test Laravel FCM Push Notifications with Pushbox

What is Pushbox?

1. Install Pushbox

2. Register a notification

3. Send a test push notification to your device

Inspect a failed send

4. Preview the notification payload before sending

5. Test notifications with different recipients

6. Compare notification variants

Check collapsed and expanded previews

7. Preview notifications in different languages

8. Restrict access

Final thoughts