PHP ssh2_disconnect() Function: Usage and Examples

ssh2_disconnect() closes an SSH session established by the PECL ssh2 extension.

What It Does

ssh2_disconnect() closes an SSH session established by the 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_disconnect(resource $session): bool

Pass a live SSH connection resource; active streams should be completed and closed first.

Example 1: Basic Behavior

Demonstrate the extension API with an explicitly trusted test server.

<?php
$session = ssh2_connect('ssh.example.test', 22);
if (!$session) throw new RuntimeException('SSH 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');
$user = getenv('SSH_USERNAME'); $password = getenv('SSH_PASSWORD');
if (!$user || !$password || !ssh2_auth_password($session, $user, $password)) throw new RuntimeException('SSH authentication failed');
if (!ssh2_disconnect($session)) throw new RuntimeException('Disconnect failed');

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) throw new RuntimeException('SSH 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');
$user = getenv('SSH_USERNAME'); $password = getenv('SSH_PASSWORD');
if (!$user || !$password || !ssh2_auth_password($session, $user, $password)) throw new RuntimeException('SSH authentication failed');
if (!ssh2_disconnect($session)) throw new RuntimeException('Disconnect failed');

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) throw new RuntimeException('SSH 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');
$user = getenv('SSH_USERNAME'); $password = getenv('SSH_PASSWORD');
if (!$user || !$password || !ssh2_auth_password($session, $user, $password)) throw new RuntimeException('SSH authentication failed');
if (!ssh2_disconnect($session)) throw new RuntimeException('Disconnect failed');

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

Streams and transfers that depend on the session must be finished before disconnection.

Comparison with Related Functions or Approaches

Common Beginner Mistakes

Key Takeaways

• ssh2_disconnect() closes an SSH session established by the PECL ssh2 extension.
• Streams and transfers that depend on the session must be finished before disconnection.
• Close SSH command streams first, then release the session.

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