README

Generic Notification is a Laravel package that records mail and SMS delivery attempts, tracks email opens through a transparent pixel, and provides a small, server-rendered delivery-log dashboard.

Support

Package	PHP	Laravel
`^2.0`	`^8.2`	`^10.0`, `^11.0`, `^12.0`
`^1.0`	`^8.0`	Legacy / unsupported

Version 2 uses the GenericNotification\\Notification namespace. For a safe upgrade, the old App\\GenericNotification\\Notification namespace and generic-notifications dashboard route remain aliases, so existing imports, manually registered providers, and navigation continue to work. New code should use the Version 2 names. Releases follow Semantic Versioning, are created from Git tags, and are documented in CHANGELOG.md. See RELEASING.md for the exact process.

Installation

composer require genericnotification/notification:^2.0
php artisan vendor:publish --tag=generic-notification-config
php artisan migrate

Laravel auto-discovers the service provider. If auto-discovery is disabled, register GenericNotification\\Notification\\GenericNotificationServiceProvider::class yourself.

Configuration and security

The published config/generic-notification.php controls route prefixes, middleware, named mailers, and SMS providers. Set the following defaults in .env when needed:

GENERIC_NOTIFICATION_DEFAULT_CC_MAIL=audits@example.com
GENERIC_NOTIFICATION_MAILER=ses
GENERIC_NOTIFICATION_SMS_PROVIDER=24x7
SMS_24X7_BASE_URL=https://provider.example/send
SMS_24X7_API_KEY=...
SMS_24X7_SENDER_ID=...
SMS_24X7_SERVICE_NAME=...

The dashboard is available at /notification-logs by default. It exposes notification payloads and must be protected in production. Add your app’s auth and authorization middleware to generic-notification.dashboard.middleware. The email-tracking endpoint is intentionally public and defaults to /notifications/email/{uuid}/pixel.png.

Default mode — no multi-vendor setup required

Nothing changes for existing users. If you do not set GENERIC_NOTIFICATION_MAILER or GENERIC_NOTIFICATION_SMS_PROVIDER, the package keeps the original behaviour:

Email uses Laravel’s default mailer and its normal .env variables, such as MAIL_MAILER, MAIL_HOST, MAIL_USERNAME, and MAIL_PASSWORD.
SMS uses the built-in 24x7 driver and SMS_24X7_* environment variables listed above.

Only set the new provider options when you need to override this default path.

Provider configuration

Email

Email delivery uses Laravel named mailers, so the package does not lock you into an email vendor. Configure providers in your application’s config/mail.php, then select one globally with GENERIC_NOTIFICATION_MAILER or per message with setMailer().

// config/mail.php — Laravel's standard named-mailer configuration
'mailers' => [
    'ses' => ['transport' => 'ses'],
    'postmark' => ['transport' => 'postmark'],
    'mailgun' => ['transport' => 'mailgun'],
    'backup-smtp' => ['transport' => 'smtp', 'host' => env('MAIL_HOST')],
],

Laravel is responsible for each provider’s SDK and credentials. This package simply uses the named mailer you choose, so its support automatically follows Laravel’s supported mail transports and custom mailers.

SMS

The package ships with 24x7 and generic http drivers. Add any HTTP SMS provider to the published config; headers and payload values may contain {phone} and {message} placeholders.

// config/generic-notification.php
'sms' => [
    'default_provider' => 'twilio',
    'providers' => [
        'twilio' => [
            'driver' => 'http',
            'url' => 'https://api.twilio.com/2010-04-01/Accounts/'.env('TWILIO_SID').'/Messages.json',
            'method' => 'post',
            'headers' => ['Authorization' => 'Basic '.base64_encode(env('TWILIO_SID').':'.env('TWILIO_AUTH_TOKEN'))],
            'payload' => ['To' => '{phone}', 'From' => env('TWILIO_FROM'), 'Body' => '{message}'],
        ],
    ],
],

Use your provider’s documented endpoint, authentication scheme, and field names. Keep credentials in environment variables or a secrets manager—never in job data or source control.

Send a tracked email

use GenericNotification\Notification\Services\Mail\MailBody;
use GenericNotification\Notification\Services\NotificationService;

$mail = new MailBody('Welcome', 'Your account is ready.');
$mail->setView('mail.welcome');
$mail->addEmail('reader@example.com');

NotificationService::notify($mail);

To route a message through a specific provider, point it at any named Laravel mailer:

$mail->setMailer('ses'); // smtp, ses, mailgun, postmark, resend, or a custom mailer from config/mail.php

In the Markdown/Blade view, render the supplied tracking code once:

{!! html_entity_decode($tracking_code ?? '') !!}

MailBody supports addCcEmail(), addAttachment(), addAttachments(), and setData() for application-specific metadata.

Send an SMS

use GenericNotification\Notification\Services\NotificationService;
use GenericNotification\Notification\Services\Sms\SmsBody;

NotificationService::notify(new SmsBody('+9199999999999', 'Your OTP is 123456'));

The built-in adapter targets 24x7 SMS by default. Select any configured SMS provider per message:

$sms = new SmsBody('+9199999999999', 'Your OTP is 123456');
$sms->setSmsProvider('twilio');
NotificationService::notify($sms);

Configure built-in HTTP providers in generic-notification.sms.providers. It supports get or post, headers, JSON payloads, and {phone} / {message} placeholders—covering Twilio, MSG91, Vonage, and other HTTP-based vendors without hard-wiring credentials. Custom drivers receive (SmsBodyInterface $body, array $provider) and must implement SmsServiceInterface.

Custom SMS driver

For an SDK-based provider, register its class as the driver instead of using the generic HTTP adapter:

'acme-sms' => [
    'driver' => App\Notifications\AcmeSmsDriver::class,
    'api_key' => env('ACME_SMS_API_KEY'),
],

The driver constructor receives SmsBodyInterface $body and array $provider, and the class must implement GenericNotification\Notification\Services\Interfaces\SmsServiceInterface.

Operations

Run a queue worker for delivery jobs:

php artisan queue:work

The package writes to generic_notifications and generic_notification_logs. The dashboard is intentionally dependency-free: no CDN assets, JavaScript framework, or client-side data table is required.

Development

composer install
composer test
composer analyse
composer lint

See CONTRIBUTING.md for contribution and release rules.

genericnotification / notification

Maintainers

Package info

Statistics

Security