PHP ssh2_sftp() Function: Usage and Examples

ssh2_sftp() opens the SFTP subsystem over an authenticated SSH session.

What It Does

ssh2_sftp() opens the SFTP subsystem over an authenticated SSH session. 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_sftp(resource $session): resource|false

Returns an SFTP subsystem resource usable with ssh2.sftp stream paths and ssh2_sftp functions.

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');
$sftp = ssh2_sftp($session);
if ($sftp === false) throw new RuntimeException('SFTP initialization failed');
$stream = fopen('ssh2.sftp://' . intval($sftp) . '/srv/data/report.csv', 'rb');
if ($stream === false) throw new RuntimeException('SFTP open failed');
echo stream_get_contents($stream);
fclose($stream);
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) 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');
$sftp = ssh2_sftp($session);
if ($sftp === false) throw new RuntimeException('SFTP initialization failed');
$stream = fopen('ssh2.sftp://' . intval($sftp) . '/srv/data/report.csv', 'rb');
if ($stream === false) throw new RuntimeException('SFTP open failed');
echo stream_get_contents($stream);
fclose($stream);
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) 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');
$sftp = ssh2_sftp($session);
if ($sftp === false) throw new RuntimeException('SFTP initialization failed');
$stream = fopen('ssh2.sftp://' . intval($sftp) . '/srv/data/report.csv', 'rb');
if ($stream === false) throw new RuntimeException('SFTP open failed');
echo stream_get_contents($stream);
fclose($stream);
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

Do not confuse SSH-based SFTP with FTP/FTPS; permissions and ssh2.sftp stream paths require careful handling.

Comparison with Related Functions or Approaches

Common Beginner Mistakes

Key Takeaways

• ssh2_sftp() opens the SFTP subsystem over an authenticated SSH session.
• Do not confuse SSH-based SFTP with FTP/FTPS; permissions and ssh2.sftp stream paths require careful handling.
• Use SCP for simple file copies and SFTP for directory and stream operations.

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