README

A comprehensive notification system for Aura CMS that provides user notifications and system updates with a beautiful slide-over panel interface.

Features

User Notifications - Laravel notification system integration with database channel
System Updates - Announce new features, security patches, and maintenance schedules
Slide-over Panel - Beautiful right-side panel with blurred backdrop
Bell Icon - Sidebar notification bell with unread count badge (toggle open/close)
Tabs - Switch between "All" notifications and "Updates"
Mark as Read - Mark individual or all notifications as read
Team Support - Filter updates by team or show global updates
Dark Mode - Full dark mode support
Responsive - Works on desktop and mobile devices

Requirements

PHP 8.1+
Laravel 10+
Aura CMS
Livewire 3.x

Installation

1. Add the plugin to your project

Copy the plugin folder to your project's plugins/aura/notifications directory.

2. Register the namespace in composer.json

Add the following to your composer.json autoload section:

{
    "autoload": {
        "psr-4": {
            "Aura\\Notifications\\": "plugins/aura/notifications/src"
        }
    }
}

Then run:

composer dump-autoload

3. Register the Service Provider

Add the service provider to your config/app.php providers array:

'providers' => [
    // ...
    Aura\Notifications\NotificationsServiceProvider::class,
],

Or if using Laravel's auto-discovery, add to your composer.json:

{
    "extra": {
        "laravel": {
            "providers": [
                "Aura\\Notifications\\NotificationsServiceProvider"
            ]
        }
    }
}

4. Run migrations

php artisan migrate

This creates the following tables:

aura_system_updates - Stores system update announcements
aura_system_update_reads - Tracks which users have read which updates

5. Publish configuration (optional)

php artisan vendor:publish --tag=aura-notifications-config

6. Add the Bell Icon to Your Sidebar

Publish Aura's navigation view if you haven't already:

php artisan vendor:publish --tag=aura-views

Then add the bell component to resources/views/vendor/aura/livewire/navigation.blade.php in the sidebar footer section, next to the user profile:

{{-- Notifications Bell --}}
<div class="ml-2 hide-collapsed">
    <livewire:aura-notifications::bell />
</div>

7. Enable notifications in Aura config

Make sure notifications are enabled in your config/aura.php:

'features' => [
    'notifications' => true,
    // ...
],

Configuration

The configuration file config/aura-notifications.php allows you to customize:

return [
    // Enable/disable notification features
    'enabled' => true,

    // System updates settings
    'system_updates' => [
        'enabled' => true,
        'categories' => [
            'feature' => 'New Feature',
            'improvement' => 'Improvement',
            'security' => 'Security Update',
            'maintenance' => 'Maintenance',
            'announcement' => 'Announcement',
        ],
    ],

    // Display settings
    'display' => [
        'max_unread_badge' => 99,
        'per_page' => 10,
    ],

    // Notification types with icons and colors
    'types' => [
        'success' => [
            'icon' => 'check-circle',
            'color' => 'green',
        ],
        'info' => [
            'icon' => 'information-circle',
            'color' => 'blue',
        ],
        'warning' => [
            'icon' => 'exclamation-triangle',
            'color' => 'yellow',
        ],
        'error' => [
            'icon' => 'x-circle',
            'color' => 'red',
        ],
    ],
];

Usage

Sending User Notifications

Use Laravel's built-in notification system. Create a notification class:

<?php

namespace App\Notifications;

use Illuminate\Notifications\Notification;

class NewCommentNotification extends Notification
{
    public function __construct(
        public string $title,
        public string $message,
        public ?string $actionUrl = null,
        public ?string $actionText = null,
        public string $level = 'info'
    ) {}

    public function via($notifiable): array
    {
        return ['database'];
    }

    public function toArray($notifiable): array
    {
        return [
            'title' => $this->title,
            'message' => $this->message,
            'action_url' => $this->actionUrl,
            'action_text' => $this->actionText,
            'level' => $this->level, // success, info, warning, error
        ];
    }
}

Send the notification:

use App\Notifications\NewCommentNotification;

$user->notify(new NewCommentNotification(
    title: 'New comment on your post',
    message: 'John left a comment: "Great article!"',
    actionUrl: route('posts.show', $post),
    actionText: 'View Comment',
    level: 'info'
));

Using the Built-in UserActionNotification

The plugin includes a ready-to-use notification class:

use Aura\Notifications\Notifications\UserActionNotification;

// Send to a single user
$user->notify(new UserActionNotification(
    title: 'Export Complete',
    body: 'Your data export has finished processing',
    level: 'success',
    url: route('exports.show', $export),
    actionText: 'View Export',
    category: 'user'
));

// Send to multiple users
use Illuminate\Support\Facades\Notification;

Notification::send($users, new UserActionNotification(
    title: 'System Maintenance',
    body: 'Scheduled maintenance on Sunday at 2 AM',
    level: 'warning'
));

Creating System Updates

Use the SystemUpdateService to create announcements:

use Aura\Notifications\Services\SystemUpdateService;

$service = app(SystemUpdateService::class);

$update = $service->createUpdate([
    'title' => 'New Dark Mode Feature',
    'slug' => 'dark-mode-v2',
    'content' => 'We have released an improved dark mode with better contrast and more color options.',
    'excerpt' => 'Dark mode is now available!',
    'category' => 'feature',
    'is_published' => true,
    'published_at' => now(),
    'is_pinned' => false,
    'team_id' => null, // null for global, or specific team ID
]);

Using the SystemUpdate Model Directly

use Aura\Notifications\Models\SystemUpdate;

// Create an update
$update = SystemUpdate::create([
    'title' => 'Security Patch Released',
    'slug' => 'security-patch-2024-01',
    'content' => 'Important security fixes have been applied.',
    'excerpt' => 'Critical security update',
    'category' => 'security',
    'is_published' => true,
    'published_at' => now(),
]);

// Get all published updates
$updates = SystemUpdate::published()->latest()->get();

// Get updates by category
$features = SystemUpdate::published()->byCategory('feature')->get();

// Check if user has read an update
$hasRead = $update->isReadBy($userId);

// Get unread updates for a user
$unread = SystemUpdate::published()
    ->whereDoesntHave('reads', fn($q) => $q->where('user_id', $userId))
    ->get();

Notification Service Methods

use Aura\Notifications\Services\NotificationService;

$service = app(NotificationService::class);

// Get user's notifications
$notifications = $service->getUserNotifications($user, 'unread'); // 'unread', 'read', 'all'

// Get unread count
$count = $service->getUnreadCount($user);

// Mark notification as read
$service->markAsRead($notification);

// Mark all as read
$service->markAllAsRead($user);

System Update Service Methods

use Aura\Notifications\Services\SystemUpdateService;

$service = app(SystemUpdateService::class);

// Get all updates for a user
$updates = $service->getAllUpdates($userId);

// Get unread updates
$unread = $service->getUnreadUpdates($userId);

// Get unread count
$count = $service->getUnreadCount($userId);

// Mark update as read
$service->markAsRead($update, $userId);

// Create a new update
$update = $service->createUpdate([...]);

// Publish an update
$service->publishUpdate($update);

Routes

The plugin registers the following routes:

Method	URI	Name	Description
GET	`/admin/notifications`	`aura.notifications.index`	Notifications list page
POST	`/admin/notifications/{id}/read`	`aura.notifications.read`	Mark notification as read
POST	`/admin/notifications/mark-all-read`	`aura.notifications.mark-all-read`	Mark all as read
GET	`/admin/updates`	`aura.updates.index`	System updates list page
GET	`/admin/updates/{slug}`	`aura.updates.show`	Single update page

Livewire Components

Bell Component

<livewire:aura-notifications::bell />

Displays the notification bell icon with unread count badge. Clicking toggles the notification panel open/closed.

Features:

White icon on dark sidebar, gray on hover
Red badge with unread count
Click to toggle panel (open → close → open)

Panel Component

<livewire:aura::notifications />

The slide-over panel component. This is automatically included by Aura CMS when config('aura.features.notifications') is enabled.

Features:

Slides in from the right side
Blurred backdrop (click to close)
~30% screen width on desktop
Tabs for "All" and "Updates"
Mark all as read functionality
Close with X button or Escape key

Customizing Views

Publish the views to customize them:

php artisan vendor:publish --tag=aura-notifications-views

Views will be published to resources/views/vendor/aura-notifications/.

Key View Files

livewire/notifications-bell.blade.php - Bell icon component
livewire/notifications-panel.blade.php - Slide-over panel
livewire/partials/compact-notifications-list.blade.php - Notification items
livewire/partials/compact-updates-list.blade.php - System update items
notifications/index.blade.php - Full notifications page
updates/index.blade.php - Full updates page
updates/show.blade.php - Single update page

Seeding Test Data

System Updates Seeder

<?php

namespace Database\Seeders;

use Aura\Notifications\Models\SystemUpdate;
use Illuminate\Database\Seeder;

class SystemUpdateSeeder extends Seeder
{
    public function run(): void
    {
        $updates = [
            [
                'title' => 'Welcome to Aura CMS',
                'slug' => 'welcome-to-aura',
                'content' => 'Thank you for choosing Aura CMS...',
                'excerpt' => 'Get started with Aura CMS',
                'category' => 'announcement',
                'is_published' => true,
                'published_at' => now(),
            ],
            [
                'title' => 'Security Update v1.0.1',
                'slug' => 'security-update-v101',
                'content' => 'Important security patches...',
                'excerpt' => 'Critical security fixes',
                'category' => 'security',
                'is_published' => true,
                'published_at' => now()->subDays(2),
            ],
        ];

        foreach ($updates as $update) {
            SystemUpdate::updateOrCreate(
                ['slug' => $update['slug']],
                $update
            );
        }
    }
}

Notifications Seeder

<?php

namespace Database\Seeders;

use App\Models\User;
use Illuminate\Database\Seeder;
use Aura\Notifications\Notifications\UserActionNotification;

class NotificationSeeder extends Seeder
{
    public function run(): void
    {
        $user = User::first();

        $notifications = [
            ['title' => 'Welcome!', 'body' => 'Welcome to the platform.', 'level' => 'success'],
            ['title' => 'New feature', 'body' => 'Check out dark mode.', 'level' => 'info'],
            ['title' => 'Password expiring', 'body' => 'Update your password.', 'level' => 'warning'],
        ];

        foreach ($notifications as $data) {
            $user->notify(new UserActionNotification(
                title: $data['title'],
                body: $data['body'],
                level: $data['level']
            ));
        }
    }
}

Events

The plugin uses the following Alpine.js events:

Event	Description
`open-notifications-panel`	Opens the notification panel
`toggle-notifications-panel`	Toggles the notification panel open/closed

And Livewire events:

Event	Description
`notificationReceived`	Refreshes the bell component
`openSlideOver`	Opens the slide-over panel
`toggleSlideOver`	Toggles the slide-over panel

Testing

Run the plugin tests:

php artisan test --filter=Notification

For browser testing with Playwright:

npx playwright test tests/playwright/notifications.spec.ts

Permissions

The plugin registers the following Gates:

Gate	Description
`view-notifications`	Can view notifications (all authenticated users)
`view-system-updates`	Can view system updates (all authenticated users)
`manage-system-updates`	Can create/edit/delete system updates (super admins)

Admin Panel

System updates can be managed through the Aura CMS admin panel:

Navigate to System > System-Updates in the sidebar
Create, edit, publish, and delete system updates
Pin important updates to show them first
Filter by category

Troubleshooting

Panel not opening

Make sure config('aura.features.notifications') is set to true
Clear view cache: php artisan view:clear
Check browser console for JavaScript errors

Two panels appearing

Ensure the panel component is only included once. Remove any duplicate <livewire:aura-notifications::panel /> from your views. The default Aura layout includes it automatically.

Bell icon not visible

The bell icon is white by default for dark sidebars. If your sidebar is light-colored, publish and customize the bell component view.

Migrations not running

If migrations don't run automatically:

php artisan vendor:publish --tag=aura-notifications-migrations
php artisan migrate

Notifications not showing

Check that notifications exist in the notifications table
Verify the user ID matches the notifiable_id in the database
Ensure notifications use the database channel

Changelog

v1.0.0

Initial release
User notifications with Laravel's database channel
System updates with read tracking
Slide-over panel with blurred backdrop
Bell icon with toggle functionality
Tabs for All/Updates
Mark all as read
Team support
Dark mode support

Credits

Bajram Emini
Built for Aura CMS
Uses Laravel Notifications
UI powered by Tailwind CSS and Alpine.js

License

The MIT License (MIT). Please see License File for more information.

eminiarts / aura-notifications

Maintainers

Details