Aura Notifications Laravel Package

Getting Started

1. Install the package

   composer require eminiarts/aura-notifications
   

2. Confirm the host app is Aura CMS. This is a plugin for Aura CMS, not a standalone Laravel package. The panel, bell icon, and sidebar slot are almost certainly registered through Aura's plugin/service-provider hooks, so verify the Aura version you run is supported before wiring it into a vanilla Laravel app.
3. Publish and migrate. Laravel's database notification channel requires a notifications table. If your app doesn't already have one, generate it with php artisan notifications:table and migrate. Also check whether the package ships its own migrations/config (php artisan vendor:publish --provider="...AuraNotificationsServiceProvider" — confirm the exact provider name in the README).
4. Add the Notifiable trait to whichever model should receive notifications (usually App\Models\User) and make sure your auth guard resolves that model.
5. First use case — the smallest end-to-end test:

   // app/Notifications/WelcomeNotice.php
   public function via($notifiable) { return ['database']; }
   
   public function toArray($notifiable)
   {
       return [
           'title' => 'Welcome aboard',
           'message' => 'Your workspace is ready.',
       ];
   }
   

   Trigger it once ($user->notify(new WelcomeNotice)), then open the sidebar bell. If the badge shows 1, the plumbing works and you can ignore the rest of the integration surface until you need it.

Where to look first: the README on GitHub is currently the only documentation referenced — read it end to end before writing code, particularly the notification payload shape, since the panel is presumably rendering your toArray()/toDatabase() keys directly.

Implementation Patterns

Separate "user notifications" from "system updates". The release notes describe two distinct streams surfaced as tabs. Treat them as two notification classes (or two payload type values) rather than one generic notifier — otherwise every future feature announcement lands in the same inbox as password-change alerts and the "Updates" tab becomes noise.

// One class per concern, not one class with a $type switch
$user->notify(new SecurityPatchAvailable($patch));  // -> Updates tab
$user->notify(new InvoiceReady($invoice));          // -> All tab

Fan-out for system updates, queue for the rest. Announcements and maintenance notices go to every user, so wrap them in a queued notification with ShouldQueue and chunk the recipient list:

User::query()->chunkById(500, fn ($users) =>
    Notification::send($users, new MaintenanceScheduled($window))
);

This keeps a release-day announcement from becoming a synchronous request that times out halfway through your user table.

Treat the bell and panel as UI you compose around, not logic you own. The package handles read/unread state and the slide-over; your job is emitting well-shaped payloads and (if needed) slotting the bell into Aura's sidebar via whatever extension point the README documents. Avoid querying the notifications table yourself for the badge count — duplicate sources of truth will drift from the package's unread logic.

Team scoping mirrors your tenancy model. If you use teams, make sure the team_id (or equivalent) you attach to update notifications matches the identifier the panel filters on. Centralise this in a base notification class or a Notification::send wrapper so a new notification type can't silently land in the wrong team's feed. Global updates should be an explicit choice (null team), not a default.

Pair with observers for domain events. The cleanest day-to-day pattern is triggering notifications from model observers or domain events (SubscriptionExpired, DeployCompleted) rather than sprinkling $user->notify(...) through controllers — you'll want the same notification fired from a scheduled command, a webhook, and an admin action eventually.

Gotchas and Tips

• It is not a drop-in for plain Laravel. The value here is Aura CMS's sidebar/panel wiring. In a standard Laravel app you'd be pulling a large CMS-coupled dependency for functionality that's a thin wrapper over notifications + Blade. Evaluate whether you actually need the Aura integration before installing.
• v1.0.0 with a README-only docs story. Expect the public API (payload keys, component names, config keys) to shift in 1.x. Pin the version in composer.json and read the diff before upgrading.
• Payload keys are a contract. Because the panel renders your toArray() output, renaming title/message will produce blank UI rather than an error. Add a small test or a shared DTO/NotificationPayload value object so a typo fails in CI instead of silently rendering nothing.
• Stale badge counts. Database notifications are not push-based unless Livewire polling or Echo is wired up. If users report the bell not updating, check the polling interval or broadcast config rather than assuming the read-state logic is broken — a hard refresh is the fastest way to tell the two apart.
• Read-state debugging. Mark-as-read writes to the notifications.read_at column. If "mark all as read" appears to do nothing, query the table directly before blaming the UI — a mismatched notifiable_type/notifiable_id (common after renaming a model or switching guards) is the usual culprit.
• Dark mode and responsive styling. Dark-mode support here will be Tailwind-based. If you run a custom Tailwind build, ensure the package's views are included in your content paths (or that it ships precompiled CSS), otherwise the panel renders unstyled in production but fine in local dev — a classic and confusing symptom.
• Blurred backdrop / z-index conflicts. A right-side slide-over with a blurred overlay will collide with existing modals, sticky headers, or Aura's own overlays. Test with your app's most layered page (a data table with a modal open) before shipping.
• Content rendering. If notification text accepts Markdown or HTML, sanitise it. System updates authored by admins are lower risk than user-generated notifications, but the same component renders both.
• Extension points to check first: publishable config (defaults for per-page counts, polling interval, tab visibility), views (to brand the panel), and any events fired on read — hook the read event if you need analytics or to clear a cached unread counter.
• Debugging tip: if nothing appears in the panel but rows exist in notifications, temporarily dd() the component's query. Nine times out of ten it's a scoping mismatch (team filter or notifiable guard) rather than a rendering bug.