Laravel integration for soloterm/notify - send desktop notifications from Artisan commands via terminal OSC escape sequences.
This package was built to support Solo, your all-in-one Laravel command to tame local development.
| OSC Notifications (Ghostty) | OSC Notifications (iTerm2) |
![]() |
![]() |
| macOS Fallback | Fireworks (iTerm2) |
![]() |
![]() |
| Progress Bars (Ghostty) | Progress Bars (iTerm2) |
![]() |
![]() |
composer require soloterm/notify-laravel --devThe service provider will be auto-discovered by Laravel.
use SoloTerm\Notify\Laravel\Facades\Notify;
// Simple notification
Notify::send('Build complete!');
// Semantic methods
Notify::success('All tests passed');
Notify::error('Build failed');
Notify::warning('Low disk space');
Notify::info('Background task started');# Simple notification
php artisan notify "Build complete!"
# With a title
php artisan notify "All tests passed" --title="Tests"
php artisan notify "All tests passed" -t "Tests"
# Force a specific protocol
php artisan notify "Hello" --protocol=osc777
php artisan notify "Hello" -p osc9
# Check terminal support
php artisan notify --info
# Full diagnostics with interactive tests
php artisan notify:diagnosePipe the exit status of any command to get automatic success/failure notifications:
# Basic usage - $? contains the exit code of the previous command
php artisan test; php artisan notify --exit-code=$?
# With npm/node commands
npm run build; php artisan notify -e $?
# Custom messages
php artisan migrate; php artisan notify -e $? --success-message="Migrations done" --failure-message="Migration failed"
# Custom titles
phpunit; php artisan notify -e $? --success-title="PHPUnit" --failure-title="PHPUnit"The Notify facade provides convenient access to all notification features:
use SoloTerm\Notify\Laravel\Facades\Notify;
// Basic notifications
Notify::send('Message', 'Title');
Notify::send('Message', 'Title', Notify::URGENCY_CRITICAL);
// Semantic methods with default titles from config
Notify::success('Task completed'); // Title: "Success"
Notify::error('Something went wrong'); // Title: "Error", critical urgency
Notify::warning('Check this out'); // Title: "Warning"
Notify::info('FYI'); // Title: "Info", low urgency
// Other methods
Notify::sendOrBell('Message'); // Falls back to bell if unsupported
Notify::sendAny('Message'); // Uses OSC or external fallback
Notify::bell(); // Just the bell characterNotify when scheduled tasks complete - perfect for long-running commands:
// In routes/console.php or app/Console/Kernel.php
// Notify after task completes
$schedule->command('backup:run')
->daily()
->thenNotify('Backup complete!');
// Notify with custom title
$schedule->command('reports:generate')
->hourly()
->thenNotify('Reports ready', 'Reports');
// Notify only on success
$schedule->command('sync:data')
->everyFiveMinutes()
->thenNotifySuccess('Sync completed');
// Notify only on failure
$schedule->command('payments:process')
->hourly()
->thenNotifyFailure('Payment processing failed!');
// Notify on both success and failure
$schedule->command('deploy:production')
->daily()
->withNotification(); // Uses command name for messages
// Custom messages for both outcomes
$schedule->command('cleanup:logs')
->weekly()
->withNotification(
successMessage: 'Cleanup finished',
failureMessage: 'Cleanup failed',
title: 'Maintenance'
);Automatically notify when Artisan commands complete:
// In config/notify.php
'events' => [
'command_finished' => [
'enabled' => true, // or env('NOTIFY_ON_COMMAND_FINISHED', false)
'success_title' => 'Command Completed',
'failure_title' => 'Command Failed',
],
'excluded_commands' => [
'notify',
'list',
'help',
// Add commands you don't want notifications for
],
],Send log messages as desktop notifications:
// In config/logging.php
'channels' => [
// ... other channels ...
'notify' => [
'driver' => 'custom',
'via' => \SoloTerm\Notify\Laravel\Logging\CreateNotifyLogger::class,
'level' => 'warning', // Only warning and above
'title' => 'My App',
],
],Then use it:
use Illuminate\Support\Facades\Log;
// Send to notify channel
Log::channel('notify')->error('Database connection lost!');
Log::channel('notify')->warning('High memory usage');
// Or add to your stack
'stack' => [
'driver' => 'stack',
'channels' => ['daily', 'notify'],
],Log levels map to urgency:
emergency,alert,critical,error→ Critical urgencywarning,notice→ Normal urgencyinfo,debug→ Low urgency
Note: This log channel is designed for CLI usage (Artisan commands, queue workers, scheduled tasks). In web requests, there's no terminal attached, so notifications are silently skipped. For web request logging, use a different channel in your stack.
Display progress in the terminal tab/taskbar for long-running commands:
use SoloTerm\Notify\Laravel\Facades\Notify;
// Check if the terminal supports progress bars
if (Notify::supportsProgress()) {
// Show progress (0-100)
Notify::progress(25);
Notify::progress(50);
Notify::progress(100);
// Clear when done
Notify::progressClear();
}// Normal progress (blue/default)
Notify::progress(75);
// Error state (red)
Notify::progressError(100);
// Paused state (yellow)
Notify::progressPaused(50);
// Indeterminate/pulsing
Notify::progressIndeterminate();
// Hide/clear
Notify::progressClear();Progress bars are supported in:
- Windows Terminal - Full support
- Ghostty - Full support (1.2+)
- iTerm2 - Full support (3.6.6+)
- ConEmu/Mintty - Full support
Get notified when queue workers start processing and when they stop:
// In AppServiceProvider or a dedicated provider
use Illuminate\Queue\Events\JobProcessing;
use Illuminate\Queue\Events\WorkerStopping;
use Illuminate\Support\Facades\Event;
use SoloTerm\Notify\Laravel\Facades\Notify;
public function boot(): void
{
// Notify when queue starts processing (first job only)
$notified = false;
Event::listen(JobProcessing::class, function () use (&$notified) {
if (!$notified) {
Notify::info('Queue worker started processing', 'Queue');
$notified = true;
}
});
// Notify when queue worker stops
Event::listen(WorkerStopping::class, function () {
Notify::warning('Queue worker stopping', 'Queue');
});
}Add notification capabilities to any Artisan command:
<?php
namespace App\Console\Commands;
use Illuminate\Console\Command;
use SoloTerm\Notify\Laravel\Concerns\SendsNotifications;
class BuildProject extends Command
{
use SendsNotifications;
protected $signature = 'build:project';
public function handle(): int
{
$this->info('Building project...');
// ... build logic ...
// Simple notification
$this->notify('Build completed!', 'Build');
// Convenience methods with preset titles
$this->notifySuccess('All tests passed');
$this->notifyError('Build failed');
$this->notifyWarning('Low disk space');
// Check if notifications are supported
if ($this->canNotify()) {
$this->notify('This terminal supports notifications!');
}
return self::SUCCESS;
}
}Publish the config file:
php artisan vendor:publish --tag=notify-configThis creates config/notify.php:
return [
// Default title when none specified
'default_title' => env('NOTIFY_DEFAULT_TITLE', 'Laravel'),
// Titles for semantic methods
'titles' => [
'success' => 'Success',
'error' => 'Error',
'warning' => 'Warning',
'info' => 'Info',
],
// Force a specific protocol (null for auto-detect)
'force_protocol' => env('NOTIFY_FORCE_PROTOCOL'),
// Enable external fallback (notify-send, osascript, etc.)
'enable_fallback' => env('NOTIFY_ENABLE_FALLBACK', true),
// Event listener configuration
'events' => [
'command_finished' => [
'enabled' => env('NOTIFY_ON_COMMAND_FINISHED', false),
'success_title' => 'Command Completed',
'failure_title' => 'Command Failed',
],
'excluded_commands' => [
'notify', 'list', 'help', 'env',
'schedule:run', 'queue:work', 'queue:listen',
],
],
];| Terminal | Support | Notes |
|---|---|---|
| iTerm2 | ✅ | macOS |
| Kitty | ✅ | Cross-platform, full-featured |
| WezTerm | ✅ | Cross-platform |
| Ghostty | ✅ | Cross-platform |
| tmux | ✅ | Requires config below |
| Alacritty | Falls back to system notifications | |
| Terminal.app | Falls back to system notifications |
For notifications to work inside tmux, add to ~/.tmux.conf:
set -g allow-passthrough onThen reload: tmux source-file ~/.tmux.conf
- PHP 8.1+
- Laravel 10, 11, or 12
- A supported terminal emulator (or system notification tools for fallback)
Part of the SoloTerm ecosystem:
- Solo - All-in-one Laravel command for local development
- Screen - Pure PHP terminal renderer
- Dumps - Laravel command to intercept dumps
- Grapheme - Unicode grapheme width calculator
- Notify - PHP package for desktop notifications via OSC escape sequences
- TNotify - Standalone, cross-platform CLI for desktop notifications
- VTail - Vendor-aware tail for Laravel logs
The MIT License (MIT).
This is free! If you want to support me:
- Check out my courses:
- Help spread the word about things I make
Developed by Aaron Francis.
- Twitter: https://twitter.com/aarondfrancis
- Website: https://aaronfrancis.com
- YouTube: https://youtube.com/@aarondfrancis





