PHP ssh2_scp_recv() Function: Usage and Examples

ssh2_scp_recv() downloads one file over SCP into a local filename.

What It Does

ssh2_scp_recv() downloads one file over SCP into a local filename. 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_scp_recv(resource $session, string $remote_file, string $local_file): bool

The source is on the SSH server and the destination is local. Paths must be approved and the return value checked.

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_scp_recv($session, '/srv/export/report.csv', '/tmp/report.csv')) throw new RuntimeException('SCP download failed');
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');
if (!ssh2_scp_recv($session, '/srv/export/status.txt', '/tmp/status.txt')) throw new RuntimeException('SCP download failed');
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');
if (!ssh2_scp_recv($session, '/srv/export/report.csv', '/tmp/snapshot.csv')) throw new RuntimeException('SCP download failed');
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

Validate server trust, local destination permissions and transfer success; SCP is not directory synchronization.

Comparison with Related Functions or Approaches

Common Beginner Mistakes

Key Takeaways

• ssh2_scp_recv() downloads one file over SCP into a local filename.
• Validate server trust, local destination permissions and transfer success; SCP is not directory synchronization.
• Use ssh2_sftp() for richer remote-file operations.

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