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

1. Adjust worker counts based on your server capacity
2. Tune memory limits per queue type in config
3. Monitor with --status command
4. 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

1. Ensure all tests pass: composer test
2. Ensure code style compliance: composer format-test
3. Update documentation if needed
4. 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 🚀