Download the PHP package multek/laravel-onesignal without Composer

Laravel OneSignal

Laravel wrapper for the official OneSignal PHP SDK. Send push notifications through a clean, fluent API, and sync OneSignal users — identity, native properties, tags, and Email/SMS subscriptions — so they're reachable through OneSignal's own email/SMS messaging (dashboard campaigns, journeys). Also tracks custom events for analytics and segmentation.

Features

• User Management — create/update/delete OneSignal users with a single upsert call carrying tags, native properties (language, timezone, country), and Email/SMS subscriptions
• Model Trait — HasOneSignal trait for syncing Eloquent models to OneSignal, sync or queued
• Push Notifications — send to users, segments, or build complex payloads with a fluent builder
• Laravel Notification Channel — send via Laravel's native notification system with OneSignalMessage
• Custom Event Tracking — track events for analytics and segmentation, gated by plan support
• Backfill Command — onesignal:backfill to sync existing records in chunks
• Zero-config local dev — disabled automatically when unconfigured; every call becomes a logged no-op
• Events — NotificationSent and NotificationFailed events for observability

Requirements

• PHP 8.2+
• Laravel 11.0+

Installation

Publish the config file:

Add your credentials to .env:

Environment variables

ONESIGNAL_ORGANIZATION_API_KEY is also available for app-level management calls; most projects won't need it.

Client-side setup (web & mobile)

This package sends notifications and syncs user data, but push subscriptions can only be created on the device itself — by OneSignal's web or mobile SDKs. Both halves share one OneSignal app, and merge into one user by using the same external_id (what getOneSignalExternalId() returns) in every SDK's login() call.

See docs/client-sdk-integration.md for the full walkthrough: Web SDK setup, mobile setup (including apps that wrap your site in a WebView, where web push does not work), and the rules that keep a multi-SDK setup consistent.

Zero-config local dev

The package is safe to leave unconfigured. If ONESIGNAL_APP_ID is empty, or ONESIGNAL_ENABLED=false is set explicitly, OneSignalManager::isEnabled() returns false and every write operation (createUser, updateUser, deleteUser, sendNotification, trackEvents, syncToOneSignalAsync()'s dispatch) becomes a no-op that writes a debug-level log line instead of calling the API. This means:

• new environments (local, CI, preview apps) work out of the box with no OneSignal account
• $user->syncToOneSignal() and friends are safe to call unconditionally from model events/observers
• turning OneSignal on in an environment is just setting ONESIGNAL_APP_ID and ONESIGNAL_REST_API_KEY

The HasOneSignal trait

Add the trait to any Eloquent model you want to sync to OneSignal:

Contract (all overridable, all have sane defaults):

Identity fields (email, phone, language, timezone, country) are never auto-written as tags — only getOneSignalTags() controls tags.

Sync methods:

Both *Async() methods check OneSignalManager::isEnabled() before dispatching — when the package is disabled, no job is queued at all (not even a no-op job). Both jobs retry 3× with a [10, 60, 300]-second backoff, so a transient OneSignal 5xx doesn't silently orphan a profile.

Keeping OneSignal in sync automatically

That is the whole integration. No field list, no wasChanged() guard, no enablement check, no queue configuration. On every save the observer asks oneSignalPayloadChanged() — which compares the payload built from the model's current attributes against the one built from its original attributes — and dispatches a sync only when they differ. Add a tag to getOneSignalTags() and it is covered the same day, with no list to update.

What the observer covers:

The last two fire no event on the user, so no user-side mechanism can see them — a hand-maintained field list misses them too. For tags derived from a relation, observe the related model:

And schedule the backfill as reconciliation rather than keeping it for emergencies:

An observer is incremental and best-effort — mass updates (User::where(...)->update()) fire no events at all. Backfill is the other half. Together they are complete; either alone is not. This is safe rather than merely hedged because the diff only decides when to talk to OneSignal, never what gets sent — anything missed is corrected in full by the next sync from any cause. SyncUserToOneSignal re-reads the model from the database when it runs (SerializesModels stores only the class and key, on every queue connection including sync), so a sync always sends current state, never a dispatch-time snapshot.

Escape hatches, in increasing order of control: omit the attribute and call User::observe(OneSignalObserver::class) yourself; write your own observer using the public oneSignalPayloadChanged(); call syncToOneSignalAsync() by hand.

With SoftDeletes the observer already does the right thing: a soft delete keeps the OneSignal profile, forceDelete() removes it, and restored resyncs. (The "Deleting on model deletion" section below recommends hooking forceDeleted for a hand-rolled deleted observer — that advice is for your own hooks; the shipped OneSignalObserver already handles the soft-delete/force-delete distinction via isForceDeleting() and needs nothing extra.)

Transactions: both SyncUserToOneSignal and DeleteUserFromOneSignal are afterCommit. saved and deleted can fire inside an open DB::transaction(); without this, a worker could pick up the job and act on the row before the transaction commits — or after it rolls back. Dispatching from inside a transaction waits for the commit instead of racing it; dispatching with no open transaction is unaffected.

Deleting on model deletion

This section is for a hand-rolled deleted hook of your own. If you're using the shipped OneSignalObserver (see above), it already distinguishes soft deletes from force deletes correctly — nothing here is needed on top of it.

deleteFromOneSignalAsync() captures the external id eagerly, so it is safe to call from a deleted hook where the row is already gone:

Two things to know:

• A 404 from OneSignal (profile never synced, or already deleted) is treated as a completed erasure — logged at debug and not retried, so idempotent deletes don't fill failed_jobs.
• With SoftDeletes, the deleted event also fires on soft deletes. If a soft delete should be reversible, hook forceDeleted instead — otherwise a restore leaves the user with no OneSignal profile until the next sync.

Deleting by id, with no model in hand (admin tooling, GDPR/LGPD erasure of an already-removed row):

Sending notifications

Facade one-liners

Fluent builder

The builder also supports toUsers(), toSegments(), excludeSegments(), withFilters(), subtitle(), addButton(), sendAfter(), throttle(), priority(), ttl(), template(), name(), and raw() (escape hatch to the underlying SDK Notification object).

Laravel notification channel

Models routing notifications use routeNotificationForOnesignal(), provided automatically by HasOneSignal (returns getOneSignalExternalId()).

Raw SDK access

Custom events

Event tracking is gated by ONESIGNAL_TRACK_EVENTS (default false). OneSignal's Free plan rejects custom events with a 403 — leave the flag off there. When the flag is off, trackEvent()/trackEvents() no-op with a debug log instead of calling the API, so it's safe to call unconditionally from application code once your plan supports events.

Backfill

Sync every record of a configured model to OneSignal in chunks:

No configuration needed on a standard Laravel app: the command resolves the model from onesignal.sync_model, falling back to your auth provider model (config('auth.providers.users.model')) and then to App\Models\User. Set ONESIGNAL_SYNC_MODEL only when the model you sync isn't the authenticated user.

The resolved class must use HasOneSignal. The command exits early with an error if it doesn't exist or lacks the trait, and warns (without failing) if OneSignal is disabled.

Testing

Run the mocked unit/feature suite (no network calls, safe in CI):

Live suite

tests/Live exercises the full user lifecycle (create, get, re-sync/upsert, update tags, track event, delete) against the real OneSignal API. It's skipped automatically unless both env vars are set:

Use a dedicated OneSignal test app — the suite creates and deletes real users.

Configuration

See config/onesignal.php for the full option reference, including default tags, queue name, sync model, and organization API key.

License

MIT