Ssh Laravel Package

Product Decisions This Supports

• Build vs. buy for remote-execution plumbing. Any feature that touches "run this on that server" — deploy hooks, cache clears, queue restarts, log tailing, backup triggers, disk-usage checks, certificate renewals — otherwise becomes bespoke proc_open + argument-escaping + key-handling code. spatie/ssh collapses that into one fluent call (Ssh::create($user, $host)->execute(...)) returning a Symfony Process, so the decision shifts from "do we build a transport layer?" to "what do we do with the result?"
• Roadmap sequencing for ops/admin features. Because the wrapper already covers port, private key, jump/bastion host, timeout, multiplexing, async execution, and streaming output (onOutput), these stop being separate roadmap items and become configuration. A PM can put "run commands across the fleet" on the roadmap without budgeting a networking workstream.
• Use cases worth scoping now:
  • Self-service server maintenance actions in an admin panel (restart service, tail log, clear cache) with streamed output back to a UI.
  • Post-deploy task runner for multi-host environments — one command array, per-host, isSuccessful() as the gate.
  • Health/diagnostics probes and scheduled audits (disk, uptime, package versions) writing results into the app.
  • Environment provisioning/first-run bootstrap via upload() + execute() (scp-based artifact push plus remote command).
  • Bastion-routed access for regulated or segmented networks via useJumpHost().
• Buy-vs-build economics favor this package on cost, not on depth. It is a thin, MIT-licensed wrapper (code lineage from Laravel Envoy) with an active changelog through Symfony 8 and PHP 8.4 support. The realistic alternative is either writing this yourself (days, then permanent maintenance) or adopting DivineOmega/php-ssh-connection (pure-PHP, no local ssh binary) — a genuine fork in the road, not a toss-up.
• Product-risk decisions it forces into the open (good): enabling password auth requires sshpass and silently fails without it; host-key checking is on by default (deliberate security posture since 1.1.1); passwords and command strings may land on the command line. Each of these is a policy decision — SSH keys/agent only, restricted command allowlists — that a PM should make explicitly rather than let an engineer discover in production.
• Interop decision: output is a Symfony Process, so results, timeouts, and exit codes plug into existing exception handling and queuing patterns. That keeps the integration reversible — the cheap-exit property a PM wants before committing.

When to Consider This Package

Adopt when:

• You already shell out to ssh/scp, or your infrastructure expects the operator's own SSH config, known_hosts, agent, and key material to be the source of truth.
• Your needs are command execution, command arrays, file push/pull, and result inspection — not protocol-level SSH.
• You want streamed output and async execution without building a concurrency layer.
• You need bastion/jump-host routing and connection reuse (useMultiplexing) for many commands against the same host.
• Your deployment target is Linux/Unix with a predictable shell, and you control both the app host (has ssh installed) and the remote hosts.
• You want a small, auditable, MIT dependency you could vendor or replace in an afternoon.

Look elsewhere or build differently when:

• You need one persistent session with SFTP operations, port forwarding, or interactive shell semantics. This package spawns a process per call; that model won't stretch.
• Process execution is unavailable or undesirable — locked-down containers with proc_open disabled, hardened hosts without ssh/scp, or a policy against spawning binaries. DivineOmega/php-ssh-connection (phpseclib) is the named alternative.
• Password authentication is a hard requirement in a controlled environment. sshpass is an external, easily-missed dependency that fails silently; prefer keys, or pick a library that does auth in-process.
• You need reliable exit-code semantics across arbitrary shells. Bash-by-default piping and cmd.exe quirks mean isSuccessful() is only trustworthy with onWindows() on Windows targets and disciplined quoting elsewhere. If your feature's correctness hinges on exit codes, budget for tests against real hosts.
• Scale matters. Thousands of hosts per run means process-per-connection overhead; consider multiplexing plus a queue, or an agent-based model (pull, not push) instead of a synchronous push.
• Ecosystem validation is a gate for you. Low dependent count and a single-maintainer, single-purpose package mean this is a "small bet you can unwind" — fine for internal tooling, weaker as a load-bearing dependency in a product you sell on reliability.
• You need structured, typed errors, retries, or idempotency out of the box. You'll be building those on top of Process, so price that work in.

How to Pitch It (Stakeholders)

To executives (30 seconds): "We need the app to run commands on our servers — for deploys, maintenance actions, and health checks. Instead of building that plumbing ourselves, we'd adopt a small, MIT-licensed, actively maintained library that does exactly one thing: run a command over SSH and hand back the result. No new servers, no new vendor, no new credentials system — it reuses the SSH keys and access rules we already have and audit. Cost is a composer require and a day of integration; the alternative is several days of custom code plus permanent ownership of a security-sensitive component."

To engineering: "It's a thin wrapper over the system ssh/scp binaries that returns a Symfony Process — so isSuccessful(), getOutput(), timeouts, and onOutput streaming are already there, and executeAsync covers fire-and-forget. It handles the annoying parts we'd otherwise hand-roll: argument construction, ports, private keys, jump hosts, multiplexing, strict host-key checking (on by default), and Windows exit codes. Test coverage and a changelog that tracks PHP 8.4 and Symfony 8 signal it's maintained. Things to design around, not fight: it does not hold a session — one process per call — so anything needing SFTP or port forwarding goes elsewhere; password auth needs sshpass and fails silently if absent, so we standardize on keys; and any user-supplied input reaching a command string must go through an allowlist, not string interpolation."

What we're knowingly accepting: a small, single-maintainer dependency; reliance on the local SSH binary and its version; process-spawn overhead per host; and no built-in retries or connection pooling beyond multiplexing. All of these are contained by the package's size and the fact that it returns a standard Process — if it disappoints, replacing it is measured in hours, not quarters. Success looks like: ops features shipped without a bespoke transport layer, zero credential-handling code written by us, and deploy/maintenance actions whose failures surface as real exit codes in our existing error handling.