Download the PHP package chijioke-ibekwe/raven without Composer

Multi-channel Laravel notification package

📝 Table of Contents

• About
• Getting Started
• Usage
• Built Using
• Authors

🧐 About

Raven is a config-driven, multi-channel notification package for Laravel. Define your notification contexts — channels and templates — in a config file, and dispatch them with a single line. No notification classes to write.

• Multi-channel — Email (SendGrid, Amazon SES, Postmark, Mailgun), SMS (Vonage, Twilio), and database/in-app notifications through one interface.
• Channel isolation — each recipient on each channel is dispatched as an independent queued job, so a failure in one doesn't block the others.
• Provider-agnostic — swap providers (e.g. Vonage to Twilio) by changing an env var. No code changes.
• Dispatch control — sync, delayed, and after-commit dispatch modes via the Scroll API.
• Encrypted payloads — optionally encrypt queued notification payloads at rest.
• Observability — RavenNotificationSent and RavenNotificationFailed events fired after each delivery attempt, per recipient.
• Artisan scaffolding — php artisan raven:make-context to interactively generate notification contexts and template files.

🏁 Getting Started

Prerequisites

To use this package, you need the following requirements:

1. PHP >= v8.1
2. Laravel >= v10.0 (v10, v11, v12, v13)
3. Composer

🎈 Usage

1. You can install this package via Composer using the command:

2. Next, publish the config files:

3. Two config files will be published to your config directory ./config:

   • raven.php — the main package configuration
   • notification-contexts.php — where you define your notification contexts (see step 4)

   The content of raven.php is as shown below:

   • The default array allows you to configure your default service providers for your notification channels. Options are sendgrid, ses, postmark, and mailgun for email, and vonage or twilio for SMS.
     • For mailgun, set MAILGUN_ENDPOINT to api.eu.mailgun.net if your Mailgun account is hosted in the EU region.
   • The providers array is where you supply the credentials for the service provider you choose.
   • The customizations array allows you to customize your email parameters, queue settings, and templates directory.
     • queue_name — sets the default queue name for all Raven notifications. The Laravel default queue is used if not provided.
     • queue_connection — sets the default queue connection for all Raven notifications. The Laravel default connection is used if not provided.
     • These global queue settings act as fallbacks. Per-channel queue routing can be configured on individual notification contexts (see step 4).
     • The default templates directory is a directory called templates in the resources path
     • The templates directory set, will contain three directories within: email, sms, and in_app.
     • The email directory will contain the .html templates for your emails.
     • The sms directory will contain the .txt files with the contents of your sms notifications.
     • The in_app directory will contain .json files whose contents will be saved on the data column of the database notifications table.
     • All placeholders in these templates should be surrounded by double curly braces e.g {{name}}.
     • File names of these templates must match the file names in the email_template_filename, sms_template_filename and in_app_template_filename keys in the notification context config entry.

4. You can create notification contexts either interactively via the artisan command, or manually in the config file.

   Option A — Using the artisan command (recommended)

   Run the following command and follow the interactive prompts:

   The command will walk you through:

   • Choosing a context name
   • Adding an optional description
   • Selecting channels (email, sms, database)
   • Choosing a template source for email contexts (provider-hosted or self-managed)
   • Optionally enabling payload encryption and per-channel queue routing

   Once confirmed, the context entry is appended to notification-contexts.php and any referenced template files are created in the appropriate subdirectories of your templates directory.

   Option B — Manual configuration

   Open the published notification-contexts.php config file and define your notification contexts. Each context is keyed by its name and contains the relevant fields for the notification type(s) it handles. Examples for each type are shown below:

   • Email Notification Context (provider-hosted template)

     Use email_template_id when the email template is hosted on the provider's platform. The provider handles rendering; Raven sends the identifier and substitution data. The value depends on your email provider:

     • SendGrid — the dynamic template ID (e.g. d-ad34ghAwe3mQRvb29)
     • Amazon SES — the template name as created via the SES CreateEmailTemplate API (e.g. MyTemplate)
     • Postmark — the template ID (numeric, e.g. 1234567) or template alias (e.g. welcome-email)
     • Mailgun — the template name as created in the Mailgun dashboard (e.g. welcome)

     Note: SES stored templates do not support attachments. An exception will be thrown if a context using a stored template includes attachments.

   • Email Notification Context (self-managed template)

     Use email_template_filename and email_subject when you manage the email template yourself as an .html file in the email subdirectory of your templates directory. Raven resolves placeholders and sends the rendered HTML to the provider.

     This works with any email provider (SendGrid, Amazon SES, Postmark, Mailgun), and you can mix both approaches across different contexts — useful for gradually migrating templates off a provider's platform.

   • SMS Notification Context

   user-verified.txt

   • Database Notification Context

   user-verified.json

   • Email, SMS and Database Notification Context

   • Context with per-channel queue routing and encrypted payloads

     • encrypted — when true, queue payloads are encrypted at rest using Laravel's ShouldBeEncrypted interface. Defaults to false.
     • queue — an optional associative array for per-channel queue routing. Each key is a lowercase channel name (email, sms, database) mapping to an array with optional queue and connection keys. Channels not listed fall back to the global queue_name/queue_connection in raven.php, then to Laravel defaults.

5. To send a notification at any point in your code, build a Scroll object, set the relevant fields as shown below, and dispatch a Raven with the Scroll:

   • for() is required and must match a notification context name defined in the notification-contexts.php config file.

   • to() is required and takes any single notifiable/email string, or an array of notifiables/email strings that should receive the notification. For email notifications, your notifiable model is expected to have an email field. If the field is named something different on the model e.g email_address, you are required to provide the routeNotificationForMail method on the model, in a similar manner as below:

     For SMS notifications, the notifiable is required to have a similar method on the notifiable model that matches the SMS provider name. For instance, if your SMS notification provider is vonage, you should have a method called routeNotificationForVonage on the notifiable, which returns the phone number field on the model. Similarly, if your provider is twilio, the method should be called routeNotificationForTwilio.

   • cc() is exclusively for email notifications and takes an array (or associative array with email/name as key/value pairs respectively) of emails you want to CC on the email notification.
   • bcc() is exclusively for email notifications and takes an associative array (email as key, name as value) of emails you want to BCC on the email notification.
   • replyTo() is exclusively for email notifications and takes an email address string to set as the reply-to address on the email notification.
   • with() takes an associative array of all the variables that exist on the notification template with their values, where the key must match the variable name on the template.
   • attach() takes a url or an array of urls that point to the publicly accessible resource(s) that needs to be attached to the email notification.

Dispatch Options

The Scroll object supports several methods for controlling dispatch behavior:

Channel override — send only specific channels, ignoring the context's channel list:

Sync dispatch — run the notification synchronously in the current process, bypassing the queue. Useful for critical notifications like password resets or OTPs:

Delayed dispatch — delay notification processing. Pass a single value for all channels, or an associative array for per-channel delays:

After commit — dispatch to the queue only after the current database transaction commits. This prevents queue workers from processing a notification before the related database changes are visible:

You can also use beforeCommit() to explicitly dispatch immediately, overriding a queue connection that has after_commit set to true by default.

Note: sync() takes precedence — when set, delay(), afterCommit(), and beforeCommit() are ignored since the job runs inline without touching the queue.

Events

Raven fires events after each per-recipient delivery attempt, allowing you to log outcomes, trigger side effects, or build dashboards.

Register listeners in your EventServiceProvider (or, from Laravel 11+, in your application's AppServiceProvider):

6. To successfully send Database Notifications, it is assumed that the user of this package has already set up a notifications table in their project via the command below:

   And subsequently:

   The data column for database notifications using this package, will capture whatever key-value pairs you have in the json template for that notification. All placeholders surrounded by {{}} in the template will be replaced with their values passed in as params of the same name when creating the Scroll object.
   NB:
   On the notifications table migration file, ensure that the notifiable column data type matches the data type for your notifiable primary key.
   By default, the data type is morphs. However, if the primary key for your notifiable is a uuid or ulid, ensure you change the type to uuidMorphs or ulidMorphs respectively.

7. The package takes care of the rest of the logic.

Exceptions

The following exceptions can be thrown by the package for the scenarios outlined below:

1. RavenContextNotFoundException code: 404
   • Dispatching a Raven with a Scroll object that has a contextName which does not exist in the notification-contexts.php config file.
2. RavenInvalidDataException code: 422
   • Dispatching a Raven with a Scroll object without a contextName or recipient.
   • Attempting to send an Email Notification using a NotificationContext that has neither an email_template_id nor an email_template_filename.
   • Attempting to send an Email Notification using a NotificationContext that has an invalid channel i.e a channel that isn't one of "EMAIL", "DATABASE", or "SMS".
   • Attempting to send an Email Notification using a NotificationContext with an email_template_filename but no email_subject.
   • Attempting to send a Database Notification using a NotificationContext that has no in_app_template_filename.
   • Attempting to send an SMS Notification using a NotificationContext that has no sms_template_filename.
   • Attempting to send a Database Notification using a NotificationContext that has a non-existent template file that matches the in_app_template_filename in the in-app template directory.
   • Attempting to send an SMS Notification using a NotificationContext that has a non-existent template file that matches the sms_template_filename in the sms template directory.
   • Attempting to send an Email Notification to a notifiable that has no email field or a routeNotificationForMail() method in the model class.
   • Attempting to send an SMS Notification to a notifiable that has no routeNotificationFor$Provider() method in the model class.
   • Attempting to send an Email Notification with attachments using a stored SES template (SES stored templates do not support attachments).
3. RavenDeliveryException code: 502
   • A notification channel (SendGrid, Amazon SES, Postmark, Mailgun, Vonage, or Twilio) fails to deliver a message due to an API error, a non-success response status, or an SDK exception. Each recipient is dispatched as a separate queued job, so failures are isolated per recipient.
4. RavenTemplateNotFoundException code: 404
   • A template file referenced by a notification context cannot be found on the filesystem.

⛏️ Built Using

• PHP - Language
• Orchestral Testbench - Library
• AWS PHP SDK - Library
• Sendgrid PHP Library - Library
• PHP Mailer - Library
• Vonage - Library
• Twilio - Library
• Postmark PHP - Library
• Mailgun PHP - Library

✍️ Authors

• @chijioke-ibekwe - Initial work