README

A CLI diagnostic tool that performs comprehensive health checks on Laravel Reverb WebSocket configurations. Stop spending hours debugging WebSocket issues — let reverb:doctor diagnose your configuration in seconds.

Features

• 10 Diagnostic Checks covering the most common Reverb configuration issues
• Actionable Suggestions for every detected problem
• Color-coded Output with PASS/FAIL/WARN/SKIP status indicators
• JSON Output for CI/CD integration
• Docker/Sail Detection with specific configuration advice
• SSL Certificate Validation including expiration warnings
• Zero Dependencies — uses only Laravel core packages

Requirements

• PHP 8.1+
• Laravel 10.x, 11.x, or 12.x
• Laravel Reverb package installed

Installation

composer require bitsoftsolutions/laravel-reverb-doctor --dev

The package will auto-register via Laravel's package discovery.

Usage

Basic Usage

php artisan reverb:doctor

Output Example

  Laravel Reverb Doctor v1.0.0

+----+-----------------------+--------+-----------------------------------------------+
| #  | Check                 | Status | Message                                       |
+----+-----------------------+--------+-----------------------------------------------+
| 1  | Environment Variables | ✓ PASS | All variables present                         |
| 2  | Config Consistency    | ✓ PASS | .env matches config files                     |
| 3  | Broadcast Connection  | ✗ FAIL | Set to 'log', should be 'reverb'              |
| 4  | Port Availability     | ✓ PASS | Port 8080 is available                        |
| 5  | Reverb Process        | ! WARN | Reverb is not running                         |
| 6  | SSL Certificate       | - SKIP | SSL not configured (using HTTP)               |
| 7  | Queue Worker          | ✓ PASS | Queue worker is running                       |
| 8  | Frontend Sync         | ✓ PASS | Frontend and server configs are in sync       |
| 9  | Docker Detection      | - SKIP | Not running in Docker                         |
| 10 | Connection Test       | ✗ FAIL | Cannot connect to localhost:8080              |
+----+-----------------------+--------+-----------------------------------------------+

  ✗ 2 failed, 1 warning, 5 passed, 2 skipped

  Suggested Fixes:

  ✗ Broadcast Connection
    Set BROADCAST_CONNECTION=reverb in your .env file

  ! Reverb Process
    Start Reverb with: php artisan reverb:start

  ✗ Connection Test
    Ensure Reverb is running: php artisan reverb:start

JSON Output (for CI/CD)

php artisan reverb:doctor --json

{
    "version": "1.0.0",
    "timestamp": "2025-12-04T12:00:00+00:00",
    "summary": {
        "passed": 5,
        "failed": 2,
        "warnings": 1,
        "skipped": 2,
        "total": 10
    },
    "checks": [
        {
            "check": "Environment Variables",
            "status": "PASS",
            "message": "All variables present",
            "suggestion": null,
            "details": {}
        }
    ]
}

Detailed Output

php artisan reverb:doctor --detailed

Shows additional diagnostic information for each check, useful for debugging complex issues.

Diagnostic Checks

Common Issues Detected

The package recognizes and provides fixes for these common error patterns:

CI/CD Integration

Use the --json flag and check the exit code:

# GitHub Actions example
- name: Check Reverb Configuration
  run: |
    php artisan reverb:doctor --json > reverb-health.json
    if [ $? -ne 0 ]; then
      echo "Reverb configuration issues detected"
      cat reverb-health.json
      exit 1
    fi

Exit codes:

• 0 — All checks passed
• 1 — One or more checks failed

Environment-Specific Notes

Docker / Laravel Sail

When running in Docker, ensure:

• REVERB_HOST is set to 0.0.0.0 (not localhost)
• Port is exposed in docker-compose.yml
• Frontend uses correct host for WebSocket connections

Laravel Valet / Herd

For HTTPS with self-signed certificates:

• The SSL check will detect Valet/Herd certificate paths
• Connection tests allow self-signed certs in local environments

Production

For production deployments:

• Ensure SSL certificates are valid and not expiring soon
• Queue workers should be running via Supervisor or similar
• Consider using a process manager for reverb:start

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

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

License

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

Credits

• Hafiz Siddiq
• All Contributors