skie/notification

Broadcasting plugin for CakePHP applications

Maintainers

Details

github.com/skie/notification

Source

Issues

Installs: 21

Dependents: 1

Suggesters: 0

Security: 0

Stars: 0

Watchers: 0

Forks: 0

Open Issues: 0

Type:cakephp-plugin

pkg:composer/skie/notification

dev-main 2025-10-21 14:48 UTC

Requires

Requires (Dev)

Suggests

MIT 09a06b50ae817fc3eaa59edc3a4423f3929f00d5

This package is auto-updated.

Last update: 2025-10-22 17:12:16 UTC

README

Database-driven notification system for CakePHP 5.x applications.

Features

  • Store notifications in database with flexible model/foreign_key pattern
  • RESTful JSON API for notification management
  • Real-time notification bell UI with auto-polling
  • Mark notifications as read/unread
  • Support for multiple notification channels (Database, Broadcasting, Email, Slack, etc.)
  • Queue support for background notification delivery
  • Testsuite support helper methods

Installation

1. Load the Plugin

In your config/plugins.php:

'Cake/Notification' => [
    'bootstrap' => true,
    'routes' => true,
],

2. Run Migrations

php bin/cake.php migrations migrate -p Cake/Notification

3. Add to Your Layout

Add the CSRF token meta tag to your layout's <head>:

<meta name="csrfToken" content="<?= $this->request->getAttribute('csrfToken') ?>">

Add the notification bell element to your navigation:

<li class="nav-item">
    <?= $this->element('Cake/Notification.notifications/bell_icon') ?>
</li>

That's it! The bell element automatically loads required CSS/JS and initializes the widget.

Usage

Creating Notifications

Option 1: Using the Notifiable Trait

use Cake\Notification\Notifiable;

class User extends Entity
{
    use Notifiable;
}

// Send a notification
$user->notify(new OrderShipped($order));

Option 2: Using NotificationManager Directly

use Cake\Notification\NotificationManager;

$manager = new NotificationManager();
$manager->send(
    $user,  // Entity or identifier
    new OrderShipped($order)  // Notification instance
);

Creating Custom Notifications

namespace App\Notification;

use Cake\Notification\Notification;

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

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

    public function toDatabase(): array
    {
        return [
            'title' => 'Order Shipped',
            'message' => "Your order #{$this->order->id} has been shipped!",
            'action_url' => "/orders/{$this->order->id}",  // Optional: makes notification clickable
            'icon' => 'post',         // Optional: built-in SVG icons (bell, post, user, message, alert, check, info)
            'icon_class' => 'fa fa-shipping-fast',  // Optional: CSS classes (Font Awesome, Bootstrap Icons, etc.)
        ];
    }

    public function toMail(): array
    {
        return [
            'subject' => 'Your order has shipped',
            'template' => 'order_shipped',
        ];
    }
}

Notification Bell Options

Customize the notification bell widget:

<?= $this->element('Cake/Notification.notifications/bell_icon', [
    'pollInterval' => 60000,  // Poll every 60 seconds (default: 30000)
    'position' => 'left',     // Dropdown position: 'left' or 'right' (default: 'right')
    'theme' => 'dark',        // Theme: 'light' or 'dark' (default: 'light')
]) ?>

Features

  • Auto-pagination: Dropdown shows 10 notifications at a time
  • Load more: Automatically shows "Load more" button when more notifications exist
  • Real-time updates: Polls for new notifications every 30 seconds (configurable)
  • Badge counter: Shows unread notification count
  • Click to navigate: If notification has action_url, clicking navigates to that URL
  • Icon support: Built-in SVG icons + CSS class icons (Font Awesome, Bootstrap Icons, etc.)

Notification Data Fields

When creating notifications, you can use these fields in your toDatabase() method:

Required Fields:

  • title - Notification title (displayed prominently)
  • message - Notification message content

Optional Fields:

  • action_url - Makes the notification clickable (navigates to this URL)
  • icon - Built-in SVG icon key (bell, post, user, message, alert, check, info)
  • icon_class - CSS class for custom icons (e.g., fa fa-bell, bi bi-bell, ti ti-bell)

Icon Options:

  1. Built-in SVG Icons (via icon field):

    • Available: bell, post, user, message, alert, check, info
    • No external dependencies, works out of the box
    • Example: 'icon' => 'post'

  2. CSS Class Icons (via icon_class field):

    • Font Awesome: 'icon_class' => 'fa fa-bell'
    • Bootstrap Icons: 'icon_class' => 'bi bi-bell'
    • Tabler Icons: 'icon_class' => 'ti ti-bell'
    • Any CSS icon library you prefer
    • Requires loading the icon library CSS in your layout
    • Example: 'icon_class' => 'fa fa-shipping-fast'

Note: If both icon and icon_class are provided, icon_class takes precedence.

API Endpoints

All endpoints return JSON and require authentication:

  • GET /notification/notifications.json - List all notifications (paginated)
  • GET /notification/notifications/unread.json - Get unread notifications
  • GET /notification/notifications/{id}.json - Get single notification
  • PATCH /notification/notifications/{id}/read.json - Mark as read
  • PATCH /notification/notifications/mark-all-read.json - Mark all as read
  • DELETE /notification/notifications/{id}.json - Delete notification
  • DELETE /notification/notifications.json - Delete all notifications

Query Parameters

  • page - Page number (default: 1)
  • limit - Results per page (default: 20)
  • status - Filter by status: all, read, unread (default: all)
  • type - Filter by notification type class name

Notification Data Fields

When creating notifications via toDatabase(), you can include these optional fields:

  • icon - Icon name: bell, post, user, message, alert, check, info (displays SVG icon)
  • title - Notification title (bold text)
  • message - Notification message (main text)
  • action_url - URL to navigate when notification is clicked (makes it clickable)

Configuration

The plugin works out of the box with sensible defaults. Configuration options coming soon.

JavaScript Events

Listen for notification events:

window.addEventListener('notification:marked-read', (e) => {
    console.log('Notification marked as read:', e.detail.notificationId);
});

window.addEventListener('notification:all-marked-read', () => {
    console.log('All notifications marked as read');
});

Requirements

  • PHP 8.1+

License

MIT License