novu / novu-laravel
Novu for Laravel
Installs: 19 344
Dependents: 0
Suggesters: 0
Security: 0
Stars: 10
Watchers: 9
Forks: 6
Open Issues: 3
Requires
- php: ^7.3|^8.0|^8.1
- ext-json: *
- illuminate/support: ~6|~7|~8|^9.0|^10.0|^11.0
- unicodeveloper/novu: ^1.2
Requires (Dev)
- mockery/mockery: ^1.1
- orchestra/testbench: ~4|~5|~6|^7.0
- pestphp/pest: ^1.20.0
- sempro/phpunit-pretty-print: ^1.0
This package is auto-updated.
Last update: 2024-10-09 05:33:12 UTC
README
Novu for Laravel
A package to easily integrate Novu into your Laravel application. Send multi-channel (SMS, Email, Chat, Push, In-App) notifications and embed Notification Centers seamlessly in your app.
Contents
Installation
PHP 7.3+ and Composer are required. Supports Laravel 7, 8, 9 and 10 out of the box.
To get the latest version of Novu Laravel, simply require it:
composer require novu/novu-laravel
Configuration
You can publish the configuration file using this command:
php artisan vendor:publish --tag="novu-laravel-config"
A configuration file named novu.php
with some sensible defaults will be placed in your config
directory:
<?php return [ /* |-------------------------------------------------------------------------- | Novu API Key |-------------------------------------------------------------------------- | | The Novu API key give you access to Novu's API. The "api_key" is | typically used to make a request to the API. | */ 'api_key' => env('NOVU_API_KEY'), /* |-------------------------------------------------------------------------- | The Novu API Base URL. |-------------------------------------------------------------------------- | | The Novu API Base URL can be a self-hosted novu api or Novu's web cloud API | typically used to make a request to Novu's service. | */ 'api_url' => env('NOVU_BASE_API_URL', 'https://api.novu.co/v1/'), ];
API Keys
Open your .env
file and add your API Key.
NOVU_API_KEY=xxxxxxxxxxxxx
Note: You need to get these credentials from your Novu Dashboard.
Usage
In-App Notification Center
Novu relies on its own JavaScript library to initiate and display the In-App Notification Center. You can load the JavaScript library by placing the @novuJS directive right before your application layout's closing </head>
tag:
<head> ... @novuJS </head>
Use the x-notification-center
Blade notification center component in the body like so:
<!DOCTYPE html> <html> <head> ... @novuJS </head> <body> <x-notification-center app-id="<YOUR_APP_IDENTIFIER>" subscriber-id="<SUBSCRIBER_ID>" style="display: inline-flex"> </x-notification-center> </body> </html>
Note: If you're using this package for a Laravel API Backend, you don't need to use this! Use the In-App Notification Center JavaScript library available for Vue, React, Angular and Vanilla JS.
Important Info
You can use the Novu
Facade or the novu()
helper function to call the methods in this package.
EVENTS
Trigger an event - send notification to subscribers:
use Novu\Laravel\Facades\Novu; $response = Novu::triggerEvent([ 'name' => '<WORKFLOW_TRIGGER_ID_FROM_DASHBOARD>', 'payload' => ['customVariables' => 'Hello'], 'to' => [ 'subscriberId' => '<SUBSCRIBER_ID_FROM_DASHBOARD>', 'phone' => '07983887777' ] ])->toArray(); // or you can use the novu() helper function like so: novu()->triggerEvent([ 'name' => '<WORKFLOW_TRIGGER_ID_FROM_DASHBOARD>', 'payload' => ['customVariables' => 'Hello'], 'to' => [ 'subscriberId' => '<SUBSCRIBER_ID_FROM_DASHBOARD>', 'phone' => '07983887777' ] ])->toArray();
Bulk Trigger events:
use Novu\Laravel\Facades\Novu; $response = Novu::bulkTriggerEvent([ [ 'name' => '<WORKFLOW_TRIGGER_ID_FROM_DASHBOARD>', 'to' => '<SUBSCRIBER_ID_FROM_DASHBOARD>', 'payload' => ['customVariables' => 'Hello'] ], [ 'name' => '<WORKFLOW_TRIGGER_ID_FROM_DASHBOARD>', 'to' => '<SUBSCRIBER_ID_FROM_DASHBOARD>', 'payload' => ['customVariables' => 'World'] ], [ 'name' => '<WORKFLOW_TRIGGER_ID_FROM_DASHBOARD>', 'to' => '<SUBSCRIBER_ID_FROM_DASHBOARD>', 'payload' => ['customVariables' => 'Again'] ] ])->toArray(); // or you can use the novu() helper function like so: novu()->bulkTriggerEvent([ [ 'name' => '<WORKFLOW_TRIGGER_ID_FROM_DASHBOARD>', 'to' => '<SUBSCRIBER_ID_FROM_DASHBOARD>', 'payload' => ['customVariables' => 'Hello'] ], [ 'name' => '<WORKFLOW_TRIGGER_ID_FROM_DASHBOARD>', 'to' => '<SUBSCRIBER_ID_FROM_DASHBOARD>', 'payload' => ['customVariables' => 'World'] ], [ 'name' => '<WORKFLOW_TRIGGER_ID_FROM_DASHBOARD>', 'to' => '<SUBSCRIBER_ID_FROM_DASHBOARD>', 'payload' => ['customVariables' => 'Again'] ] ])->toArray();
Trigger an event - send notification to topics
use Novu\Laravel\Facades\Novu; $response = Novu::triggerEvent([ 'name' => '<event_name>', 'payload' => ['customVariables' => 'Hello'], 'to' => [ [ 'type' => 'Topic', 'topicKey' => $topicKey ], [ 'type' => 'Topic', 'topicKey' => $topicSecondKey ] ] ])->toArray();
Broadcast event to all existing subscribers:
use Novu\Laravel\Facades\Novu; $response = Novu::broadcastEvent([ 'name' => '<WORKFLOW_TRIGGER_ID_FROM_DASHBOARD>', 'payload' => ['customVariables' => 'Hello'], 'transactionId' => '<REPLACE_WITH_TRANSACTION_ID>' ])->toArray();
Cancel triggered event. Using a previously generated transactionId during the event trigger, this action will cancel any active or pending workflows:
use Novu\Laravel\Facades\Novu; $response = Novu::cancelEvent($transactionId);
SUBSCRIBERS
use Novu\Laravel\Facades\Novu; // Get list of subscribers $subscribers = Novu::getSubscriberList(); // Create subscriber & get the details of the recently created subscriber returned. $subscriber = Novu::createSubscriber([ 'subscriberId' => '<YOUR_SYSTEM_USER_ID>', 'email' => '<insert-email>', // optional 'firstName' => '<insert-firstname>', // optional 'lastName' => '<insert-lastname>', // optional 'phone' => '<insert-phone>', //optional 'avatar' => '<insert-avatar>', // optional ])->toArray(); // Bulk create subscribers $response = Novu::bulkCreateSubscribers([ [ 'subscriberId' => '<SUBSCRIBER_IDENTIFIER>', 'email' => '<insert-email>', // optional 'firstName' => '<insert-firstname>', // optional 'lastName' => '<insert-lastname>', // optional 'avatar' => '<insert-avatar>', // optional ], [ 'subscriberId' => '<SUBSCRIBER_IDENTIFIER>', 'email' => '<insert-email>', // optional 'firstName' => '<insert-firstname>', // optional 'lastName' => '<insert-lastname>', // optional 'avatar' => '<insert-avatar>', // optional ], ]); // Get subscriber $subscriber = Novu::getSubscriber($subscriberId)->toArray(); // Update subscriber $subscriber = Novu::updateSubscriber($subscriberId, [ 'email' => '<insert-email>', // optional 'firstName' => '<insert-firstname>', // optional 'lastName' => '<insert-lastname>', // optional 'phone' => '<insert-phone>', //optional 'avatar' => '<insert-avatar>', // optional ])->toArray(); // Delete subscriber Novu::deleteSubscriber($subscriberId); // Update subscriber credentials $response = Novu::updateSubscriberCredentials($subscriberId, [ 'providerId' => '<insert-providerId>', 'credentials' => '<insert-credentials>' ])->toArray(); // Update subscriber online status $isOnlineStatus = true; // or false $response = Novu::updateSubscriberOnlineStatus($subscriberId, $isOnlineStatus)->toArray(); // Get subscriber preferences $preferences = Novu::getSubscriberPreferences($subscriberId)->toArray(); // Update subscriber preference Novu::updateSubscriberPreference($subscriberId, $templateId, [ 'channel' => 'insert-channel', 'enabled' => 'insert-boolean-value' // optional ]); // Get a notification feed for a particular subscriber $feed = Novu::getNotificationFeedForSubscriber($subscriberId); // Get the unseen notification count for subscribers feed $count = Novu::getUnseenNotificationCountForSubscriber($subscriberId); // Mark a subscriber feed message as seen Novu::markSubscriberFeedMessageAsSeen($subscriberId, $messageId, []); // Mark message action as seen Novu::markSubscriberMessageActionAsSeen($subscriberId, $messageId, $type, []);
TOPICS
use Novu\Laravel\Facades\Novu; // Create a Topic Novu::createTopic([ 'key' => 'frontend-users', 'name' => 'All frontend users' ]); // Fetch all topics Novu::getTopics(); // Get a topic Novu::topic($topicKey); // Add subscribers to a topic $subscribers = [ '63e271488c028c44fd3a64e7', '3445' ]; Novu::topic($topicKey)->addSubscribers($subscribers); // Remove subscribers from a topic $subscribers = [ '63e271488c028c44fd3a64e7', '3445' ]; Novu::topic($topicKey)->removeSubscribers($subscribers); // Rename a topic Novu::topic($topicKey)->rename($topicName);
ACTIVITY
use Novu\Laravel\Facades\Novu; // Get activity feed $feed = Novu::getActivityFeed(); // Get activity statistics $stats = Novu::getActivityStatistics()->toArray(); // Get activity graph statistics $graphStats = Novu::getActivityGraphStatistics()->toArray();
INTEGRATIONS
use Novu\Laravel\Facades\Novu; // Get integrations Novu::getIntegrations()->toArray(); // Create integration Novu::createIntegration([ 'providerId' => '<insert->provider->id>', 'channel' => '<insert->channel>', 'credentials' => [ // insert all the fields ], 'active' => true, 'check' => true ])->toArray(); // Get active integrations Novu::getActiveIntegrations()->toArray(); // Get webhook support status for provider Novu::getWebhookSupportStatusForProvider($providerId)->toArray(); // Update integration Novu::updateIntegration($integrationId, [ 'active' => true, 'credentials' => [ // insert all the fields ], 'check' => true ])->toArray(); // Delete integration Novu::deleteIntegration($integrationId);
LAYOUTS
use Novu\Laravel\Facades\Novu; // filter layouts Novu::filterLayouts(['pageSize' => 1])->toArray(); // Create layout Novu::createLayout([ 'name' => '<insert-name-of-layout>', 'identifier' => '<insert-identifier>', 'content' => '<insert-html-content>', ])->toArray(); // Get a layout Novu::getLayout('<insert-layout-id>')->toArray(); // Set Layout as default Novu::setLayoutAsDefault('<insert-layout-id>'); // Update layout Novu::updateLayout('<insert-layout-id>', [ 'name' => '<insert-name-of-layout>', 'identifier' => '<insert-identifier>', 'content' => '<insert-html-content>', ])->toArray(); // Delete layout Novu::deleteLayout('<insert-layout-id>');
NOTIFICATIONS
use Novu\Laravel\Facades\Novu; // Get all notifications Novu::getNotifications()->toArray(); // Get all notifications with query parameters $queryParams = [ 'page' => 3 ]; Novu::getNotifications($queryParams)->toArray(); // Get one notification Novu::getNotification($notificationId)->toArray(); // Get notification stats Novu::getNotificationStats()->toArray(); // Get Notification graph stats Novu::getNotificationGraphStats()->toArray(); // Get Notification graph stats with query parameters $queryParams = [ 'days' => 5 ]; Novu::getNotificationGraphStats($queryParams)->toArray();
NOTIFICATION TEMPLATES
use Novu\Laravel\Facades\Novu; // Get notification templates Novu::getNotificationTemplates()->toArray(); // Create notification template Novu::createNotificationTemplate([ "name" => "name", "notificationGroupId" => "notificationGroupId", "tags" => ["tags"], "description" => "description", "steps" => ["steps"], "active" => true, "draft" => true, "critical" => true, "preferenceSettings" => preferenceSettings ])->toArray(); // Update notification template Novu::updateNotificationTemplate($templateId, [ "name" => "name", "tags" => ["tags"], "description" => "description", "identifier" => "identifier", "steps" => ["steps"], "notificationGroupId" => "notificationGroupId", "active" => true, "critical" => true, "preferenceSettings" => preferenceSettings ])->toArray(); // Delete notification template Novu::deleteNotificationTemplate($templateId); // Get notification template Novu::getANotificationTemplate($templateId); // Update notification template status Novu::updateNotificationTemplateStatus($templateId, [ 'active' => true ])
NOTIFICATION GROUPS
use Novu\Laravel\Facades\Novu; // Create Notification group Novu::createNotificationGroup([ 'name' => '<insert-name>' ]); // Get Notification groups Novu::getNotificationGroups()->toArray();
CHANGES
use Novu\Laravel\Facades\Novu; // Get changes Novu::getChanges(); // Get changes count Novu::getChangesCount()->toArray(); // Apply changes Novu::applyBulkChanges([ 'changeIds' = [ '<insert-all-the-change-ids>' ] ])->toArray(); // Apply change Novu::applyChange($changeId, []);
ENVIRONMENTS
use Novu\Laravel\Facades\Novu; // Get current environment Novu::getCurrentEnvironment()->toArray(); // Create environment Novu::createEnvironment([ 'name' => '<insert-name>', 'parentId' => '<insert-parent-id>' // optional ])->toArray(); // Get environments Novu::getEnvironments()->toArray(); // Update environment by id Novu::updateEnvironment($envId, [ "name" => "name", "identifier" => "identifier", "parentId" => "parentId" ]); // Get API KEYS Novu::getEnvironmentsAPIKeys()->toArray(); // Regenerate API KEYS $key = Novu::regenerateEnvironmentsAPIKeys()->toArray(); // Update Widget Settings Novu::updateWidgetSettings([ 'notificationCenterEncryption' => true ]);
FEEDS
use Novu\Laravel\Facades\Novu; // Create feed Novu::createFeed([ 'name' => '<insert-name-for-feed>' ]); // Get feeds Novu::getFeeds()->toArray(); // Delete feed Novu::deleteFeed();
MESSAGES
use Novu\Laravel\Facades\Novu; // Get messages Novu::getMessages([ 'page' => 1, 'channel' => ['<insert-channel>'], ]); // Delete message Novu::deleteMessage();
EXECUTION DETAILS
use Novu\Laravel\Facades\Novu; // Get execution details Novu::getExecutionDetails([ 'notificationId' => '<insert-notification-id>', 'subscriberId' => '<insert-subscriber-id>' ])->toArray();
TENANTS
use Novu\Laravel\Facades\Novu; // Create tenant Novu::createTenant([ 'identifier' => '<identifier>', 'name' => '<name>', ]); // Get tenants Novu::getTenants()->toArray();
Validate the MX Record setup for Inbound Parse functionality
use Novu\Laravel\Facades\Novu; // Validate MX Record for Inbound Parse Novu::validateMXRecordForInboundParse()->toArray();
License
Licensed under the MIT license.