PHP ssh2_connect() Function: Usage and Examples

ssh2_connect() opens an SSH transport session using the optional PECL ssh2 extension.

What It Does

ssh2_connect() opens an SSH transport session using the optional PECL ssh2 extension. The following examples distinguish a normal use case, a boundary case and a practical application.

Requirements and Compatibility

PECL ssh2, an approved SSH server, trusted host-key pinning and valid SSH credentials. This optional extension is not part of core PHP.

PECL ssh2 host fingerprints are typically exposed as SHA-1 or MD5; always compare a trusted, pre-approved host key value before authenticating, and prefer mature clients with stronger host-key policies where practical.

Syntax, Parameters and Return Value

ssh2_connect(string $host, int $port = 22, array $methods = [], array $callbacks = []): resource|false

Host and port select the server. Methods and callbacks customize the SSH handshake; check the server identity before authentication.

Example 1: Basic Behavior

Demonstrate the extension API with an explicitly trusted test server.

<?php
$session = ssh2_connect('ssh.example.test', 22);
if ($session === false) throw new RuntimeException('Connection failed');
$expected = getenv('SSH_HOST_FINGERPRINT_SHA1');
if (!$expected || !hash_equals(strtolower($expected), strtolower(ssh2_fingerprint($session, SSH2_FINGERPRINT_SHA1 | SSH2_FINGERPRINT_HEX)))) throw new RuntimeException('Untrusted SSH server');
ssh2_disconnect($session);

This example depends on an installed extension, third-party library or configured service and is not a standalone local test.

Example 2: Another Case

Use a second approved host and check the operation result.

<?php
$session = ssh2_connect('internal-ssh.example.test', 22);
if ($session === false) throw new RuntimeException('Connection failed');
$expected = getenv('SSH_HOST_FINGERPRINT_SHA1');
if (!$expected || !hash_equals(strtolower($expected), strtolower(ssh2_fingerprint($session, SSH2_FINGERPRINT_SHA1 | SSH2_FINGERPRINT_HEX)))) throw new RuntimeException('Untrusted SSH server');
ssh2_disconnect($session);

This example depends on an installed extension, third-party library or configured service and is not a standalone local test.

Practical Example: Putting It to Use

Apply the operation in a controlled backup or administrative workflow; never pass arbitrary user commands.

<?php
$session = ssh2_connect('backup-ssh.example.test', 22);
if ($session === false) throw new RuntimeException('Connection failed');
$expected = getenv('SSH_HOST_FINGERPRINT_SHA1');
if (!$expected || !hash_equals(strtolower($expected), strtolower(ssh2_fingerprint($session, SSH2_FINGERPRINT_SHA1 | SSH2_FINGERPRINT_HEX)))) throw new RuntimeException('Untrusted SSH server');
ssh2_disconnect($session);

This example depends on an installed extension, third-party library or configured service and is not a standalone local test.

Important Behavior and Edge Cases

Opening an SSH connection does not authenticate a user or verify the expected server identity for you.

Comparison with Related Functions or Approaches

Common Beginner Mistakes

Key Takeaways

• ssh2_connect() opens an SSH transport session using the optional PECL ssh2 extension.
• Opening an SSH connection does not authenticate a user or verify the expected server identity for you.
• Verify the host fingerprint against a trusted value before ssh2_auth_password() or key-based login.

Before adapting these examples, verify the return values, test the failure paths and confirm that your application meets its security and environment requirements.