Getting Started

Install the package via Composer:

composer require spatie/global-laravel-remote

Publish the config file (optional but recommended for customization):

php artisan vendor:publish --provider="Spatie\GlobalLaravelRemote\GlobalLaravelRemoteServiceProvider"

Configure your SSH connection details in .env or config/global-laravel-remote.php:

GLOBAL_LARAVEL_REMOTE_CONNECTION=production
GLOBAL_LARAVEL_REMOTE_PRODUCTION_HOST=your-server.com
GLOBAL_LARAVEL_REMOTE_PRODUCTION_USERNAME=deploy
GLOBAL_LARAVEL_REMOTE_PRODUCTION_KEY_PATH=~/.ssh/id_rsa

Run your first remote command:

php artisan remote:run production -- artisan migrate

For a quick test, verify connectivity:

php artisan remote:run production -- php -v

Implementation Patterns

1. Remote Command Execution

Use remote:run for one-off commands:

php artisan remote:run staging -- artisan queue:work --once

Best Practice: Store frequently used commands in a Makefile or shell script for reusability.

2. Remote Artisan Commands with Arguments

Pass arguments directly:

php artisan remote:run production -- artisan cache:clear --env=production

For complex flags, use -- to separate Artisan from the remote command:

php artisan remote:run production -- --env=production --force

3. Environment-Specific Workflows

Define multiple connections in config/global-laravel-remote.php:

'connections' => [
    'local' => [
        'host' => 'localhost',
        'username' => 'forge',
        'keyPath' => '~/.ssh/id_rsa',
    ],
    'staging' => [
        'host' => 'staging.example.com',
        'username' => 'deploy',
        'keyPath' => storage_path('ssh/staging_key'),
    ],
],

Run commands against specific environments:

php artisan remote:run staging -- artisan config:clear

4. Integration with Laravel Tasks

Use the RemoteCommand facade in custom Artisan commands:

use Spatie\GlobalLaravelRemote\Facades\RemoteCommand;

class DeployCommand extends Command {
    public function handle() {
        RemoteCommand::run('production', 'artisan deploy:run');
    }
}

5. Parallel Execution

Leverage SSH multiplexing (via ~/.ssh/config) for faster connections:

Host production
    HostName production.example.com
    User deploy
    IdentityFile ~/.ssh/production_key
    ControlMaster auto
    ControlPath ~/.ssh/control:%h:%p:%r
    ControlPersist 1h

6. Logging and Debugging

Enable verbose output for troubleshooting:

php artisan remote:run production -- -vvv artisan optimize

Check logs in storage/logs/laravel.log for connection issues.

Gotchas and Tips

Common Pitfalls

Key Permissions Ensure SSH keys have 600 permissions:
```
chmod 600 ~/.ssh/id_rsa
```
Fix: Run chmod -R 755 ~/.ssh if permissions are incorrect.
Environment Mismatch Remote commands default to the local environment. Explicitly specify --env:
```
php artisan remote:run production -- artisan config:clear --env=production
```

Command Timeouts Default timeout is 30 seconds. Increase for long-running tasks:

'timeout' => 60, // in config

Or pass via CLI:

php artisan remote:run production -- --timeout=120 artisan optimize

Firewall/SSH Restrictions Ensure your server allows SSH connections on port 22 (or custom port). Test with:
```
ssh -T deploy@your-server.com
```
Laravel Version Mismatch Remote commands execute on the server’s Laravel version. Avoid running commands requiring local dependencies (e.g., php artisan vendor:publish).

Debugging Tips

Test SSH Manually Verify connectivity before using the package:
```
ssh -i ~/.ssh/id_rsa deploy@your-server.com "php -v"
```
Check Remote Laravel Version Run this to confirm compatibility:
```
php artisan remote:run production -- php artisan --version
```
Enable SSH Debugging Add -vvv to SSH commands in the package’s config (requires customization):
```
'sshOptions' => ['-vvv'],
```

Extension Points

Custom SSH Config Override SSH options per connection:

'connections' => [
    'production' => [
        'sshOptions' => ['-p', '2222'], // Custom port
    ],
],

Pre/Post-Command Hooks Extend the RemoteCommand facade to add logic:

RemoteCommand::extend(function ($command) {
    if (str_contains($command, 'deploy')) {
        RemoteCommand::run('production', 'artisan down');
        // Run deploy command...
        RemoteCommand::run('production', 'artisan up');
    }
});

Local-to-Remote File Sync Combine with spatie/laravel-ssh for file transfers:

php artisan ssh:run production -- "scp -r /local/path user@remote:/remote/path"

Pro Tips

Use Aliases Add shortcuts to your ~/.bashrc:

alias deploy='php artisan remote:run production -- artisan deploy'

Monitor Long-Running Jobs Use screen or tmux on the remote server for persistent processes:
```
php artisan remote:run production -- "screen -dmS queue php artisan queue:work"
```
Cache Remote Connections Reduce latency by reusing SSH connections (handled automatically via ControlMaster).

Global Laravel Remote Laravel Package