Weave Code
Onesignal Laravel Package
laravel-notification-channels/onesignal
OneSignal notification channel for Laravel. Send push notifications through OneSignal using Laravel’s notification system, with support for segments, filters, custom data, buttons, and platform-specific delivery options.
OneSignal Notifications driver
Frequently asked questions about Onesignal
- How do I install laravel-notification-channels/onesignal in a Laravel app?
- Install it with composer require laravel-notification-channels/onesignal, then publish the package config if you need to override defaults. Add your OneSignal app_id and REST API key to config/services.php and reference them from the package config rather than hardcoding values. After that you implement toOneSignal() and routeNotificationForOneSignal() on your Notifiable model and add 'onesignal' to the notification's via() array. For a queued notification, remember to implement ShouldQueue so the HTTP call happens off the request cycle.
- Which Laravel and PHP versions does this OneSignal channel support?
- Version 2.8.1 is a compatibility release that adds Laravel 13.x support, contributed by laravel-shift, and the package has tracked the Laravel 10/11/12 era with a PHP 8.1+ floor. Always read the composer.json of the exact version you pin, because Illuminate version bounds, the PHP floor, and the Guzzle major can change between releases. If your application matrix is older Laravel or older PHP, verify constraints before upgrading rather than assuming backward compatibility.
- How do I send a OneSignal push notification from a Laravel notification?
- Create a notification class and add 'onesignal' to its via() method, then define toOneSignal($notifiable) returning a OneSignalMessage with your content, headings, data, buttons, and delivery options. Define routeNotificationForOneSignal() on the notifiable to return the OneSignal identity used for targeting. Laravel keeps ownership of the domain event and templating while OneSignal handles mobile push delivery, which is the intended separation.
- Does this package support OneSignal external_id and subscription IDs, or only legacy player IDs?
- It depends on the released version you pin, because OneSignal has been migrating from the v1 surface with player IDs and include_player_ids to a v2 surface with app-scoped paths, external_id, and subscription IDs. The channel is a thin adapter, so the targeting shape it exposes mirrors whichever API version that release was written against. Confirm against the pinned source code, not the changelog, and plan the migration path for when that OneSignal API version sunsets.
- Why do my OneSignal notifications report success but never arrive?
- OneSignal can return HTTP 200 with a populated errors array in the response body, so a channel that only inspects the status code will treat a failed send as delivered. Check whether your pinned version parses the response body, and if it does not, wrap the call and inspect the payload yourself. Also confirm the target identity actually maps to an active subscription in OneSignal before blaming the channel.
- Is it safe to keep the OneSignal REST API key in my .env file?
- The REST API key can send push notifications to your entire user base, so treat it as a high-value production secret. Store it in a vault or secret manager, restrict access, and rotate it on a schedule or after any suspected exposure, rather than committing it to .env by habit. Because the blast radius is app-wide, use separate keys or apps per environment to limit the impact of a leak.
- Can I target segments, filters, or topics instead of a single user with this channel?
- Yes. The channel supports segments, filters, custom data, buttons, and platform-specific delivery options, so you can broadcast to a segment or build filter expressions rather than only sending direct-to-user messages. Exact support for scheduled delivery and newer OneSignal topic constructs should be verified against the pinned release. Remember that data payload size limits and English-default content fields are upstream constraints you need to design around.
- Is laravel-notification-channels/onesignal actively maintained?
- It is community-maintained under the laravel-notification-channels organization, MIT licensed, with roughly 294 stars and no SLA. The 2.8.1 release shows the project still accepts maintenance patches, including from laravel-shift, the official Laravel upgrade service, which is a positive liveness signal. That is evidence of activity, not a support commitment, so assume a real bus factor and be prepared to fork or patch.
- Does this package handle device registration and permission prompts?
- No. The channel covers delivery only, so device and subscription registration, permission prompts, and external-ID lifecycle management all live in your mobile client. That work is routinely underestimated as out of scope and then becomes the critical path for the feature. Budget for it on the mobile side even though the PHP integration is only a few days of effort.
- How do I test OneSignal push notifications in a Laravel test suite?
- Use Notification::fake() and assert the notification was sent to the expected notifiables with assertSentTo, so your tests do not hit the OneSignal API. For unit-testing the message payload itself, instantiate the OneSignalMessage and assert on the generated array. If you want to cover the channel's HTTP behavior, fake the underlying Guzzle handler so you can return both success and the errors-in-200 response shape and confirm your error handling catches the latter.
Weaver
How can I help you explore Laravel packages today?