Product Decisions This Supports
- Build vs. buy for messaging plumbing: This package is a thin transport layer over OneSignal's REST API using Laravel's
Http client and a single OneSignal facade. It removes the boilerplate decision (auth headers, base URL, JSON decoding, error handling) but not the integration design work. Choose it over hand-rolling a client only if your roadmap stays within the methods it exposes.
- Scoping a notification feature: Coverage supports a credible v1 — send/list/get/cancel notifications, list/create/delete segments, get/create/delete users, list/get/create templates, and read app config. That is enough for "send a push to a segment," "cancel a scheduled send," and "manage audiences and reusable copy." It is not enough to claim full OneSignal parity.
- Roadmap risk to flag now: Templates are read/create only (no update/delete), users are get/create/delete (no update, no identity/alias or subscription management — the area OneSignal has been actively reshaping), segments have no update, and app is read-only. Any roadmap item like "let marketers edit templates in-app" or "sync subscription preferences" forces a raw
Http:: call alongside the package, which is the worst outcome: two integration styles in one codebase.
- Uncovered capabilities to plan around: No webhooks/event ingestion, no export/import, no batch or multi-app handling, and no mention of retries, rate-limit backoff, or idempotency keys for sends. Notification delivery is a retry-sensitive, duplicate-sensitive domain — treat these as product requirements to verify, not implementation details.
- Vendor-lock-in posture: Because the surface is thin and OneSignal-specific (
OneSignalException carrying decoded error bodies), swapping providers later means rewriting call sites, not just config. Budget for an internal interface if provider optionality is a real strategic concern.
When to Consider This Package
Adopt when:
- You are on Laravel and already committed to OneSignal as the delivery provider.
- Your needs map to the exposed verbs: transactional or campaign push to segments, canceling scheduled sends, basic user registration/deletion, list-and-create templates.
- You want typed exceptions and decoded error bodies out of the box rather than parsing raw responses.
- The team is small and maintaining a bespoke HTTP client is not worth the surface area — this is a reasonable, honest wrapper.
Look elsewhere or wrap it when:
- You need template management as a first-class product feature (edit/delete/version), subscription or identity management, or webhook-driven delivery analytics — none are covered.
- You require multi-app/multi-tenant routing, idempotent sends, or documented retry/rate-limit behavior; none are described in this release.
- You need test doubles — no fakes or
Http::fake helpers are mentioned, so plan your own contract tests around the facade.
- v1.0.0 is a first release with no public track record. Pin the version, read the diff before upgrades, and assume the API surface will shift as OneSignal's own API evolves. Treat it as a dependency to wrap behind your own small service class so a breaking change is a one-file fix.
How to Pitch It (Stakeholders)
To executives: A small, free, single-purpose library that lets our Laravel app send and manage OneSignal push notifications — send, cancel, target segments, manage users and templates — without us building or maintaining that glue code. It saves days of setup, not weeks of product work. It covers the core send path only; richer use cases (template editing, subscription preferences, delivery analytics via webhooks) would still require custom work, so it does not change our headcount or timeline estimates.
To engineering: Thin, unsurprising wrapper: one facade, Laravel's Http client underneath, non-2xx responses throw OneSignalException with the decoded OneSignal error body — so error handling is consistent and debuggable. Read the surface before committing: templates lack update/delete, users lack update and subscription/identity operations, segments lack update, app is read-only, and there is no webhook support or documented retry/idempotency behavior. Wrap it in a single internal service class, add Http::fake-based tests ourselves, pin the version, and route any missing endpoint through that same service so we never end up with two integration styles.