Laravel Desktop Notifier Laravel Package

Getting Started

1. Install the package via Composer:

   composer require nunomaduro/laravel-desktop-notifier
   

   No service provider or config file is needed — the package uses Laravel's auto-discovery.

2. Start using it in your Artisan commands by calling $this->notify() in the handle() method:

   $this->notify('Deployment complete', 'Production build finished successfully.');
   

   On first use, the system will attempt to display a native desktop notification (requires running on a desktop environment — not in pure CLI headless contexts like production CI).

3. Add an optional icon for richer visuals:

   $this->notify('Success', 'Task completed', resource_path('img/icon.png'));
   

Implementation Patterns

• In long-running commands: Use to signal progress milestones without requiring constant terminal monitoring:

  $this->notify('Step 1', 'Database migration started');
  // ...
  $this->notify('Step 2', 'Database migration completed', '✅');
  

• In deployment/CI hooks: Trigger notifications from local deploy scripts or interactive deploy commands (e.g., php artisan deploy) to alert you when background tasks finish.

• With custom icons: Define reusable icon paths (e.g., resource_path('icons/app.png')) and wrap in a helper trait or base command class for consistency:

  protected function success(string $title, string $body): void
  {
      $this->notify($title, $body, resource_path('icons/success.png'));
  }
  

• Conditional notifications: Skip desktop alerts when not in an interactive or GUI-enabled environment (e.g., in CI):

  if ($this->output->isVerbose()) {
      $this->notify('Debug', 'Configuration reloaded');
  }
  

Gotchas and Tips

• ❗ No notification in non-GUI environments: Desktop notifications only appear if the system has a graphical environment (e.g., local dev machine). In headless servers (e.g., Docker containers, production servers), calls will silently no-op or emit warnings depending on OS.

• ⚙️ Quiet mode override: If your command is invoked with --quiet, $this->notify() still attempts to show desktop alerts — consider wrapping critical calls:

  if (! $this->option('quiet')) {
      $this->notify(...);
  }
  

• 🖼️ Icon requirements vary by OS:

  • macOS: PNG recommended (≤ 512×512 px).
  • Windows: .ico or .png; large icons may be clipped.
  • Linux: Supports PNG; desktop environment (e.g., GNOME, KDE) must support desktop notifications.

• 🔁 Not for end-user alerts: This package is strictly for developer/local workflow feedback, not production user-facing notifications.

• 🔌 Hook into events: Use in artisan bootstrapping or event listeners to notify on infrastructure events (e.g., cache clear, queue drain) during development:

  Event::listen(JobProcessed::class, fn () => $this->notify('Job', 'Processed successfully'));
  

• 🧪 Test safety: Desktop notifiers do not throw exceptions by default — handle failures manually if logging/alerting is needed:

  $success = $this->notify('Test', 'Alert');
  // No return value — rely on OS behavior; no built-in success check
  

• ⏱️ Upgrade early for Laravel compatibility: As seen in changelog, new releases often add compatibility ahead of Laravel versions — check for updates before upgrading Laravel core.