README

A production-grade, auditable, queue-safe notification system for Laravel.

This package is designed for reliability, traceability, and clarity, not magic. If you forget how it works in 6 months — read this file and you’ll be productive again.

Table of Contents

1. Overview & Philosophy
2. Architecture & Mental Model
3. Supported Channels
4. Template System (DB → Blade → Inline)
5. Standard Template Keys
6. Installation
7. Configuration
8. Usage Examples
9. Queueing & Retry Behavior
10. Logging & Auditing
11. Seeders & Default Templates
12. Blade Templates (Fallbacks)
13. What This Package Does NOT Do
14. Production Checklist

1. Overview & Philosophy

This package treats notifications as delivery intents, not just messages.

• Delivery is observable
• Failures are audited
• Retries are intentional
• Templates are versioned
• Channels are isolated

This is suitable for:

• Financial systems
• Security alerts
• Compliance-heavy domains
• Multi-channel delivery (Email, SMS, Slack, In-App)

2. Architecture & Mental Model

Core Components

• Notifier → Orchestrates delivery (sync vs queue)
• SendNotificationJob → Async execution + retries
• Channels → Email, SMS, Slack, In-App
• NotificationTemplate → Versioned content (DB)
• Blade Templates → File-based fallback
• NotificationLogger → Single source of audit truth

Template Resolution Order

1. Database template
2. Published Blade template (host app)
3. Package Blade template
4. Inline body (last resort)

3. Supported Channels

4. Template System

Templates are channel-specific and versioned.

Database columns:

• key
• channel
• subject (nullable)
• body
• version

Never edit templates in-place. Increment the version instead.

5. Standard Template Keys

System

• system.critical
• system.warning
• system.info

Authentication

• auth.otp
• auth.login_alert
• auth.password_reset

User Lifecycle

• user.welcome
• user.profile_updated
• user.deactivated

Security

• security.suspicious_login
• security.password_changed

Business (Generic)

• transaction.success
• transaction.failed
• document.ready

6. Installation

composer require michael-orenda/notification

Publish config (optional):

php artisan vendor:publish --tag=notification-config

7. Configuration

Queueing

'queue' => env('NOTIFICATION_QUEUE', false),
'queue_name' => 'notifications',

Retry & Backoff

'retry' => [
    'count' => 5,
    'backoff' => [1, 3, 5, 10, 20],
],

Per-channel overrides

'sms' => [
    'retries' => 6,
    'backoff' => [1, 3, 5, 10, 20],
],

8. Usage Examples

Basic Send

use MichaelOrenda\Notification\Services\Notifier;

$notifier->send(
    $user,
    'system.critical',
    [
        'content' => 'Disk usage exceeded 95%',
        'server' => 'prod-01',
    ],
    ['email', 'sms']
);

Inline Body (no template)

$notifier->send($user, [
    'body' => 'Simple text message',
], [], ['sms']);

9. Queueing & Retry Behavior

When NOTIFICATION_QUEUE=true:

• Notifications are dispatched to a queue
• Retries are attempt-based
• Exponential backoff is applied
• Highest-risk channel controls retry behavior

Run worker:

php artisan queue:work --queue=notifications

10. Logging & Auditing

All delivery attempts are stored in:

notification_deliveries

Each record includes:

• channel
• provider
• destination
• template key + version
• status (sent, failed)
• error (if any)

This table is your audit trail.

11. Seeders & Default Templates

A default seeder is provided:

MichaelOrenda\Notification\Database\Seeders\NotificationTemplateSeeder

Run:

php artisan db:seed --class="MichaelOrenda\\Notification\\Database\\Seeders\\NotificationTemplateSeeder"

This seeds:

• Email templates
• SMS templates
• In-App templates
• Slack templates

12. Blade Templates (Fallback)

Package fallbacks live in:

resources/views/emails/
resources/views/sms/
resources/views/slack/

Host apps may override by publishing views.

13. What This Package Does NOT Do

Intentionally excluded:

• ❌ UI rendering
• ❌ User preference screens
• ❌ Cron-based scheduling
• ❌ Marketing campaigns

Those belong in higher-level packages.

14. Production Checklist

Before shipping:

• Enable queue mode
• Configure retries & backoff
• Seed templates
• Start queue workers
• Monitor notification_deliveries

Final Note

This package favors correctness over convenience.

If something fails:

• You will know
• You will have logs
• You will not lose notifications

Ship with confidence.