README

Multi-channel notification system for WPZylos Framework — Send notifications through mail, database, and admin notices with a clean, extensible API.

✨ Features

📧 Mail Channel — Send email notifications via WPZylos MailManager or wp_mail() fallback
💾 Database Channel — Persist notifications for in-app inbox patterns (read/unread)
🔔 Admin Notice Channel — Display WordPress dashboard notices via transients
🔌 Extensible Channels — Implement NotificationChannel to create custom channels (Slack, SMS, etc.)
🎯 Notifiable Trait — Add notify() to any model or entity with one trait
✉️ Fluent Message Builders — MailMessage and AdminNoticeMessage DTOs with chainable API
🏗️ Database Installer — Auto-create notifications table with dbDelta()
⚡ Error Resilient — Channel failures fire wpzylos_notification_failed action without breaking the chain
🏛️ Service Provider — Zero-config container registration with NotificationServiceProvider

📋 Requirements

Requirement	Version
PHP	>= 8.0
WordPress	>= 5.9
wpzylos-core	^1.0
wpzylos-database	^1.0 (optional, for DatabaseChannel)

📦 Installation

composer require wpdiggerstudio/wpzylos-notification

🚀 Quick Start

1. Register the Service Provider

use WPZylos\Framework\Notification\NotificationServiceProvider;

// In your plugin bootstrap:
$app->register(new NotificationServiceProvider());

2. Create a Notification

<?php

declare(strict_types=1);

namespace App\Notifications;

use WPZylos\Framework\Notification\Notification;
use WPZylos\Framework\Notification\MailMessage;

class OrderShipped extends Notification
{
    public function __construct(private object $order) {}

    public function via(): array
    {
        return ['mail', 'database'];
    }

    public function toMail(object $notifiable): MailMessage
    {
        return (new MailMessage())
            ->subject('Order Shipped!')
            ->greeting('Hello!')
            ->line('Your order #' . $this->order->id . ' has been shipped.')
            ->action('Track Order', $this->order->tracking_url);
    }

    public function toDatabase(object $notifiable): array
    {
        return [
            'order_id' => $this->order->id,
            'message'  => 'Your order has been shipped.',
        ];
    }
}

3. Make Your Model Notifiable

<?php

declare(strict_types=1);

namespace App\Models;

use WPZylos\Framework\Notification\Notifiable;

class User
{
    use Notifiable;

    public int $id;
    public string $email;

    public function routeNotificationFor(string $channel): mixed
    {
        return match ($channel) {
            'mail' => $this->email,
            'database', 'admin_notice' => $this->id,
            default => null,
        };
    }
}

4. Send It!

$user->notify(new OrderShipped($order));

📖 Core Features

Multi-Channel Dispatch

Send a single notification through multiple channels simultaneously:

class PaymentReceived extends Notification
{
    public function via(): array
    {
        // Notify via email, store in database, AND show admin notice
        return ['mail', 'database', 'admin_notice'];
    }
}

Fluent Mail Messages

Build rich HTML emails with the chainable MailMessage API:

public function toMail(object $notifiable): MailMessage
{
    return (new MailMessage())
        ->subject('Payment Received')
        ->greeting('Thank you!')
        ->line('We received your payment of $99.00.')
        ->line('Your subscription is now active.')
        ->action('View Dashboard', 'https://example.com/dashboard')
        ->level('success');
}

Admin Dashboard Notices

Display dismissible notices in the WordPress admin:

use WPZylos\Framework\Notification\AdminNoticeMessage;

public function toAdminNotice(object $notifiable): AdminNoticeMessage
{
    return (new AdminNoticeMessage())
        ->message('A new order has been placed!')
        ->type('success')
        ->dismissible(true);
}

Database Notification Inbox

Query stored notifications with the Notifiable trait:

// Get all notifications
$notifications = $user->notifications();

// Get only unread
$unread = $user->unreadNotifications();

// Get only read
$read = $user->readNotifications();

// Mark as read
$user->markNotificationAsRead($notificationId);

Custom Channels

Create your own notification channels:

<?php

declare(strict_types=1);

namespace App\Channels;

use WPZylos\Framework\Notification\Contracts\NotificationChannel;
use WPZylos\Framework\Notification\Notification;

class SlackChannel implements NotificationChannel
{
    public function send(object $notifiable, Notification $notification): void
    {
        if (method_exists($notification, 'toSlack')) {
            $data = $notification->toSlack($notifiable);
            // Send to Slack webhook...
        }
    }
}

// Register it:
$manager->extend('slack', new SlackChannel());

Direct Manager Usage

Send notifications without the trait:

use WPZylos\Framework\Notification\NotificationManager;

$manager = $app->make(NotificationManager::class);

// Send to one notifiable
$manager->send($user, new OrderShipped($order));

// Send to multiple notifiables
$manager->send([$user1, $user2, $admin], new OrderShipped($order));

Database Table Installation

Set up the notifications table during plugin activation:

use WPZylos\Framework\Notification\DatabaseNotificationInstaller;

$installer = $app->make(DatabaseNotificationInstaller::class);
$installer->install();

// On uninstall:
$installer->uninstall();

📚 Related Packages

Package	Description
wpzylos-core	Core framework (required)
wpzylos-database	Database layer for DatabaseChannel
wpzylos-mail	Advanced email sending
wpzylos-model	Notifiable models
wpzylos-queue	Queue notifications for async delivery

📖 Documentation

Full documentation is available at https://wpzylos.com/docs/latest/packages/wpzylos-notification.

Support the Project

📄 License

This package is open-sourced software licensed under the MIT License.

🤝 Contributing

Please see CONTRIBUTING.md for details on how to contribute.

Made with ❤️ by WPDiggerStudio

wpdiggerstudio / wpzylos-notification

Maintainers

Package info

Fund package maintenance!

Statistics

Security