Laravel Onesignal Laravel Package

Getting Started

Install the package with Composer, then publish its config:

composer require <vendor>/laravel-onesignal
php artisan vendor:publish --tag=onesignal-config

Add your OneSignal credentials to .env:

ONESIGNAL_APP_ID=your-app-id
ONESIGNAL_REST_API_KEY=your-rest-api-key

The package exposes a OneSignal facade backed by Laravel’s HTTP client. If your app does not use package discovery, register the service provider and facade alias manually.

Look first at:

• config/onesignal.php for app ID, REST key, base URL, and HTTP options.
• The OneSignal facade and its notifications/segments/users/templates/app resource classes.
• OneSignalException for the decoded API error body.

Your first use case should be a simple transactional notification, typically from a queued listener:

use Vendor\OneSignal\Facades\OneSignal;

OneSignal::notifications()->send([
    'included_segments' => ['All'],
    'headings' => ['en' => 'Order shipped'],
    'contents' => ['en' => "Order #{$order->id} is on its way."],
    'data' => ['order_id' => $order->id],
]);

Check whether the package injects app_id automatically. If not, include 'app_id' => config('onesignal.app_id') in the payload.

Implementation Patterns

Wrap the facade in your own application service or action class. This keeps OneSignal payload details out of controllers and listeners, and gives you one place to handle retries, logging, and testing.

Send notifications from queued jobs or events rather than inside HTTP requests:

class SendOrderShippedNotification implements ShouldQueue
{
    use Queueable;

    public function handle(OneSignalNotifier $notifier): void
    {
        $notifier->sendToUser($this->order->user, 'Order shipped', '...');
    }
}

Target users consistently. Map your Laravel user ID to OneSignal’s external_user_id, then use include_external_user_ids or the users API instead of storing OneSignal player IDs yourself.

Use templates for copy that changes frequently. Create templates through the package, store the returned template ID in config or the database, and send notifications by template_id. This avoids redeploying when marketing or product copy changes.

Treat segments as coarse audiences: plan tiers, roles, or lifecycle stages. Avoid creating a segment per user; OneSignal segments are not a substitute for user-level targeting.

For testing, use Laravel’s HTTP fake support:

Http::fake([
    'onesignal.com/*' => Http::response(['id' => 'notification-id'], 200),
]);

OneSignal::notifications()->send([...]);

Http::assertSent(fn ($request) => $request['contents']['en'] === 'Hello');

Also fake non-2xx responses to verify your OneSignalException handling and user-facing fallback behavior.

Use separate OneSignal apps and REST keys per environment. Keep production keys out of local and test environments, and cache config with php artisan config:cache after deployment.

Gotchas and Tips

• Non-2xx responses throw OneSignalException with the decoded error body. Catch it at your job or service boundary, log the body, and decide whether the failure is retryable. Do not let raw OneSignal errors reach end users.
• Verify whether app_id is auto-injected. If it is not, every payload must include it; missing app IDs typically produce a 400 with a vague message.
• OneSignal payload keys are easy to mistype: included_segments, include_external_user_ids, contents, headings. A typo often becomes a 400 rather than a silent no-op, but validate payloads before sending.
• List endpoints are paginated. Do not assume notifications()->list() or similar returns every record; pass and handle limit/offset explicitly.
• Retries can duplicate notifications. If you use Http::retry() or job retries, make sends idempotent where possible, or restrict retries to connection failures and 5xx/429 responses.
• Respect rate limits. A 429 should back off, not retry immediately. Bulk sends belong in queued jobs with throttling.
• The release exposes create/list/get for most resources, but not full CRUD everywhere. Templates, for example, may not support update or delete in v1.0.0; design around immutable templates or create new versions.
• Deleting users and segments is destructive and immediate. Guard those calls behind admin authorization and avoid running them from generic cleanup jobs without dry-run support.
• There is no webhook or delivery-receipt support in this release. For opens, clicks, or delivery failures, use OneSignal’s dashboard or add your own webhook endpoint outside the package.
• Configure HTTP timeouts in the package config or when binding your own client. The default Laravel HTTP timeout may be too long for request-cycle sends and too short for large segment operations.
• For extension, bind your own wrapper service around the facade rather than calling OneSignal:: directly throughout the codebase. That gives you a seam for mocking, feature flags, and future package upgrades.