README

Laravel Nexus is your central hub for queue worker management. It automatically discovers your queues, provides interactive configuration, and manages multiple workers with beautiful real-time logging and hot reload capabilities.

🤔 Why Laravel Nexus?

Tired of this? 😤

# The daily struggle with complex Laravel apps...
php artisan queue:work --queue=default &
php artisan queue:work --queue=broadcasting --timeout=30 &
php artisan queue:work --queue=mail --timeout=120 &
php artisan queue:work --queue=notifications --sleep=1 &
php artisan queue:work --queue=edi-processing --timeout=300 --memory=256 &
php artisan queue:work --queue=payments --tries=5 &

# ...and trying to manage/monitor them all locally! 😵‍💫

Laravel Nexus was born from this exact frustration!

Instead of juggling multiple terminal windows and remembering different queue configurations, Laravel Nexus lets you:

✨ Run ONE command to manage ALL your queues 🔍 Auto-discover all queues in your app ⚙️ Configure once, run everywhere 📺 Monitor everything in one beautiful interface

# The Laravel Nexus way ✨
php artisan nexus:work --log

That's it! All your queues running with optimized settings, beautiful logs, and zero mental overhead.

✨ Features

🔍 Auto-Discovery - Scans Jobs, Events, Mail, Notifications, and Listeners
⚙️ Interactive Setup - Beautiful Laravel Prompts for easy configuration
📺 Live Log Streaming - Real-time, color-coded worker output
🎛️ Process Management - Start, stop, restart, and monitor workers
🔥 Hot Reload - Auto-restart workers when files change (perfect for development)
🔄 Auto-restart - Responds to Laravel's queue:restart signals
📊 Smart Defaults - Optimized settings based on queue type
🚀 Production Ready - Built for reliability and performance
✅ Thoroughly Tested - Comprehensive test suite with 31 tests covering all functionality

🧪 Testing & Quality

Laravel Nexus is thoroughly tested with a comprehensive test suite:

31 Tests covering all package functionality
Unit Tests for core services and queue discovery
Feature Tests for all commands and workflows
Architecture Tests ensuring code quality and standards
CI/CD Pipeline testing against PHP 8.1, 8.2, 8.3, 8.4 and Laravel 10.x, 11.x, 12.x
Code Style enforcement with Laravel Pint
Security Auditing with automated dependency scanning

# Run the test suite
composer test

# Check code formatting
composer format-test

# Auto-fix code style
composer format

Installation

Install the package via Composer:

composer require jamesjulius/laravel-nexus --dev

The package will automatically register its service provider.

Optionally, publish the configuration file:

# Simple way
php artisan nexus:publish

# Or using vendor:publish directly
php artisan vendor:publish --provider="JamesJulius\LaravelNexus\NexusServiceProvider" --tag="nexus-config"

Quick Start

1. Interactive Setup (Recommended)

Run the interactive configuration to discover and set up your queues:

php artisan nexus:configure

This will:

🔍 Scan your app for Jobs, Events, Mail, and Notifications
📋 Show discovered queues with job counts and statistics
⚙️ Let you configure worker settings interactively
💾 Save configuration to config/nexus.php
🚀 Optionally start workers immediately

2. Start Workers

Start your configured workers:

# Basic daemon mode
php artisan nexus:work

# Development with live logs
php artisan nexus:work --log

# Development with hot reload
php artisan nexus:work --watch

# Debug mode with job IDs and timestamps
php artisan nexus:work --detailed

3. Management Commands

# Publish configuration (optional)
php artisan nexus:publish

# Check worker status
php artisan nexus:work --status

# Stop all workers
php artisan nexus:work --stop

# Restart all workers
php artisan nexus:work --restart

# Get comprehensive help
php artisan nexus:help

Commands Reference

Configuration Management

# Publish configuration file
php artisan nexus:publish
php artisan nexus:publish --force  # Overwrite existing

# Interactive setup flow
php artisan nexus:configure

# Discovery only (no configuration)
php artisan nexus:configure --discover

# List all jobs by queue
php artisan nexus:configure --list-jobs

# List jobs for specific queue
php artisan nexus:configure --list-jobs --queue=broadcasting

Worker Management

# Start all workers
php artisan nexus:work

# Start with live log streaming
php artisan nexus:work --log

# Start with detailed logging (job IDs, dates, colors)
php artisan nexus:work --detailed

# Start with file watching + auto-reload
php artisan nexus:work --watch

# Worker lifecycle management
php artisan nexus:work --status    # Check status
php artisan nexus:work --stop      # Stop all workers
php artisan nexus:work --restart   # Restart workers

# Start specific worker only
php artisan nexus:work --worker=broadcasting

Help & Documentation

# Comprehensive help guide
php artisan nexus:help

# Command-specific help
php artisan help nexus:configure
php artisan help nexus:work

Configuration

The package automatically generates a config/nexus.php file with your queue configurations:

<?php

return [
    'workers' => [
        'default' => [
            'queue' => 'default',
            'connection' => env('QUEUE_CONNECTION', 'database'),
            'tries' => 3,
            'timeout' => 60,
            'sleep' => 3,
            'memory' => 128,
            'processes' => 2,
            'max_jobs' => 1000,
            'max_time' => 3600,
        ],
        'broadcasting' => [
            'queue' => 'broadcasting',
            'connection' => env('QUEUE_CONNECTION', 'database'),
            'tries' => 3,
            'timeout' => 30,
            'sleep' => 1,
            'memory' => 128,
            'processes' => 1,
            'max_jobs' => 500,
            'max_time' => 3600,
        ],
        // ... more workers
    ],

    'environment' => env('APP_ENV', 'production'),
    'prefix' => env('NEXUS_PREFIX', 'nexus'),
    'auto_restart' => true,
    'restart_signal_file' => storage_path('framework/cache/laravel-queue-restart'),
];

Advanced Configuration Options

Laravel Nexus now offers advanced configuration modes to reduce repetitive configuration across multiple queues:

Global Defaults Mode

When configuring multiple queues, you can set global defaults that apply to all workers:

php artisan nexus:configure
# Select your queues
# Choose "Yes" for "Would you like to configure advanced global defaults?"

This lets you set:

Default timeout per job (seconds)
Default memory limit per worker (MB)
Default max retry attempts
Default sleep time between jobs
Default max jobs per worker before restart
Default max worker runtime

Simplified Configuration Mode

For teams that don't want to configure timeout/memory for every queue:

php artisan nexus:configure
# Enable advanced global defaults
# Choose "Yes" for "Use simplified configuration mode?"

In simplified mode, you only configure:

Worker count per queue (the most important setting)
Everything else uses smart defaults or your global settings

This is perfect when you want to:

🚀 Quick setup - Just set worker counts, use smart defaults
🎯 Focus on scaling - Configure what matters most (process count)
📊 Consistent settings - Same timeout/memory across all queues

Configuration Flow Example

⚙️  Laravel Nexus Configuration
🔍 Discovering queues...

📋 Queue Selection:
✅ default (5 job types)
✅ mail (2 job types)
✅ broadcasting (3 job types)

Would you like to configure advanced global defaults? (yes)

⚙️  Global Default Settings:
Default timeout per job (seconds): 120
Default memory limit per worker (MB): 256
Default max retry attempts: 3
Default sleep time between jobs (seconds): 3
Default max jobs per worker before restart: 1000
Default max worker runtime (seconds): 3600

Use simplified configuration mode? (yes)

Configuring queue: default
Number of worker processes: 2

Configuring queue: mail
Number of worker processes: 1

Configuring queue: broadcasting
Number of worker processes: 1

📝 Final Configuration:
default: 2 process(es)
mail: 1 process(es)
broadcasting: 1 process(es)

Save this configuration? (yes)
✅ Configuration saved to config/nexus.php

Start workers now? (yes)
🚀 Starting workers...

Queue Auto-Discovery

Laravel Nexus automatically discovers queues from:

Jobs with $queue property or onQueue() calls
Broadcasting Events with broadcastQueue() method
Mail Classes using the Queueable trait
Notifications implementing ShouldQueue
Event Listeners that are queued

Example Queue Detection

// Jobs
class ProcessPayment implements ShouldQueue
{
    public $queue = 'payments'; // ✅ Detected
}

// Events
class OrderShipped implements ShouldBroadcast
{
    public function broadcastQueue()
    {
        return 'broadcasting'; // ✅ Detected
    }
}

// Mail
class WelcomeEmail extends Mailable implements ShouldQueue
{
    use Queueable;

    public function __construct()
    {
        $this->onQueue('mail'); // ✅ Detected
    }
}

// Notifications
class InvoiceGenerated extends Notification implements ShouldQueue
{
    public $queue = 'notifications'; // ✅ Detected
}

Development Workflow

Hot Reload

Perfect for development - automatically restarts workers when files change:

php artisan nexus:work --watch

Monitors:

app/ directory
config/ directory
routes/ directory
database/migrations/ directory
resources/views/ directory

Live Logging

Stream worker logs in real-time with beautiful color coding:

# Basic live logs
php artisan nexus:work --log

# Detailed logs with job IDs and timestamps
php artisan nexus:work --detailed

Log Features:

✅ Color-coded job statuses (Processing=Orange, Success=Green, Failed=Red)
🎯 Job class highlighting
📊 Memory usage and duration highlighting
🆔 Job ID extraction in detailed mode
⏰ Smart timestamp formatting

Production Usage

Basic Setup

# 1. Configure queues
php artisan nexus:configure

# 2. Start workers (use process manager like Supervisor)
php artisan nexus:work

Supervisor Configuration

[program:nexus-workers]
process_name=%(program_name)s_%(process_num)02d
command=php /path/to/your/app/artisan nexus:work
autostart=true
autorestart=true
redirect_stderr=true
stdout_logfile=/path/to/your/app/storage/logs/nexus.log
numprocs=1

Health Monitoring

# Check worker status in scripts/cron
php artisan nexus:work --status

# Restart workers during deployment
php artisan nexus:work --restart

# Or use Laravel's built-in restart signal
php artisan queue:restart  # Nexus auto-detects this

Environment Variables

# Queue connection (standard Laravel)
QUEUE_CONNECTION=database

# Nexus-specific settings
NEXUS_PREFIX=nexus

Troubleshooting

No Queues Detected

# Re-scan for queues
php artisan nexus:configure --discover

# Check specific queue
php artisan nexus:configure --list-jobs --queue=default

Workers Not Starting

# Check configuration
cat config/nexus.php

# Check worker status
php artisan nexus:work --status

# Force restart
php artisan nexus:work --restart

Performance Issues

Adjust worker counts based on your server capacity
Tune memory limits per queue type in config
Monitor with --status command
Use appropriate timeouts for different job types

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

# Clone the repository
git clone https://github.com/jamesjulius/laravel-nexus.git
cd laravel-nexus

# Install dependencies
composer install

# Run tests
composer test

# Check code style
composer format-test

# Fix code style
composer format

Testing Guidelines

All new features must include tests
Tests should cover both success and failure scenarios
Run the full test suite before submitting PRs
Follow the existing test patterns and structure

Pull Request Process

Ensure all tests pass: composer test
Ensure code style compliance: composer format-test
Update documentation if needed
Submit PR with clear description of changes

License

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

Credits

James Julius - Initial development
Built with ❤️ for the Laravel community

Laravel Nexus - Your central hub for queue worker management 🚀

jamesjulius / laravel-nexus

Maintainers

Details