Laravel OneSignal

A thin Laravel wrapper for the OneSignal REST API. Covers notifications, segments, users and templates through a simple, typed API built on Laravel's Http client.

Features

• Notifications: send, list, get, cancel
• Segments: list, create, delete
• Users: get, create, delete
• Templates: list, get, create
• App: get
• Notification targeting precedence: segments > emails > player IDs > aliases > default Subscribed Users segment
• Throws OneSignalException (with the original API error body) on any non-2xx response

Installation

You can install the package via composer:

composer require jeffersongoncalves/laravel-onesignal

Publish the config file:

php artisan vendor:publish --tag=laravel-onesignal-config

Set your OneSignal App ID and REST API key in .env:

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

Both are found under Settings > Keys & IDs in your OneSignal dashboard.

Configuration

// config/laravel-onesignal.php
return [
    'app_id' => env('ONESIGNAL_APP_ID', ''),
    'rest_api_key' => env('ONESIGNAL_REST_API_KEY', ''),
];

Usage

The package is resolved via the OneSignal facade or by injecting JeffersonGoncalves\LaravelOnesignal\OneSignal. Each resource is exposed as a method returning a dedicated resource class.

Notifications

use JeffersonGoncalves\LaravelOnesignal\Facades\OneSignal;

// Defaults to the "Subscribed Users" segment
OneSignal::notifications()->send('Hello world!', heading: 'Hi there');

// Target specific segments
OneSignal::notifications()->send('Hello!', segments: ['Active Users']);

// Target specific emails, player IDs or aliases
OneSignal::notifications()->send('Hello!', emails: ['jane@example.com']);
OneSignal::notifications()->send('Hello!', playerIds: ['player-id']);
OneSignal::notifications()->send('Hello!', aliases: ['external_id' => ['user-1']], channel: 'push');

$notifications = OneSignal::notifications()->list(limit: 10, offset: 0);

$notification = OneSignal::notifications()->get('notification-id');

OneSignal::notifications()->cancel('notification-id');

Targeting precedence when multiple options are given: segments > emails > playerIds > aliases > the default Subscribed Users segment.

Segments

$segments = OneSignal::segments()->list(limit: 10, offset: 0);

// Default filter: session_count > 0
OneSignal::segments()->create('Active Users');

OneSignal::segments()->create('VIPs', [
    ['field' => 'tag', 'key' => 'vip', 'relation' => '=', 'value' => 'true'],
]);

OneSignal::segments()->delete('segment-id');

Users

$user = OneSignal::users()->get('user-1');
$user = OneSignal::users()->get('onesignal-id', 'onesignal_id');

OneSignal::users()->create(externalId: 'user-1', email: 'jane@example.com', tags: ['plan' => 'pro']);

OneSignal::users()->delete('user-1');

Templates

$templates = OneSignal::templates()->list(limit: 10, offset: 0);

$template = OneSignal::templates()->get('template-id');

OneSignal::templates()->create('Welcome', message: 'Hi there!', heading: 'Welcome!');

App

$app = OneSignal::app()->get();

Error handling

Any non-2xx API response throws JeffersonGoncalves\LaravelOnesignal\Exceptions\OneSignalException, which exposes the decoded error body:

use JeffersonGoncalves\LaravelOnesignal\Exceptions\OneSignalException;

try {
    OneSignal::notifications()->send('Hello!');
} catch (OneSignalException $e) {
    logger()->error($e->getMessage(), $e->errorBody());
}

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Jefferson Gonçalves
• All Contributors

License

The MIT License (MIT). Please see License File for more information.