Ssh Laravel Package

Getting Started

Start by installing the package with Composer: composer require spatie/ssh. Then use the fluent, human-readable Ssh facade to execute remote commands:

use Spatie\Ssh\Ssh;

$process = Ssh::create('deploy', 'myapp.example.com')->execute('php artisan migrate');
if ($process->isSuccessful()) {
    echo $process->getOutput();
}

The package wraps Symfony’s Process component — so it’s familiar if you’ve used Laravel’s Process::run() or Artisan::call(). First real-world use case: automate deployment tasks across servers.

Implementation Patterns

• Batch execution: Run multiple shell commands in sequence on the same connection by passing an array to execute() — ideal for CI/CD pipelines or health checks.
• Real-time streaming: Use onOutput(fn($type, $line) => ...), not only getOutput() — perfect for streaming logs or interactive CLI wrappers.
• Credential management: Prefer SSH keys over passwords (usePrivateKey()), but when passwords are unavoidable (legacy systems), ensure sshpass is installed — the package fails silently otherwise.
• File transfers: Use upload() and download() for secure file syncs without extra dependencies — backed by scp under the hood.
• Async workloads: Spawn long-running tasks with executeAsync() and check their status later, e.g., artisan queue:work --timeout=0 triggered from a web hook.

Gotchas and Tips

• Windows targets: Use removeBash() when connecting to Windows machines (e.g., via OpenSSH server) to avoid bash wrapper injection in commands.
• Timeouts tripwires: Setting setTimeout() affects the total SSH process runtime, not the remote command — and was historically buggy for scp uploads/downlaods; verify in your version.
• Quiet mode gotcha: enableQuietMode() suppresses prompts (e.g., for host key confirmation) — useful for automation, but pair with disableStrictHostKeyChecking() if ephemeral/test hosts are involved.
• Multiplexing performance: Enable useMultiplexing() for repeated SSH calls to the same host — dramatically reduces connection latency (especially over high-latency networks).
• Debugging tip: If commands hang or fail with no output, run php -r "var_dump(\Scape\ssh\Process::create(...)->run(...));" manually — also check getErrorOutput() separately; SSH errors often land there.
• Extension point: Use configureProcess() to tweak Symfony Process options — e.g., disable setTimeout(null) for interactive shells or set custom env vars.