PHP ssh2_scp_send() Function: Usage and Examples

ssh2_scp_send() uploads a local file over SCP to a remote destination.

What It Does

ssh2_scp_send() uploads a local file over SCP to a remote destination. 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_send(resource $session, string $local_file, string $remote_file, int $create_mode = 0644): bool

The source is local and the destination is remote. The optional permission mode affects file creation.

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_send($session, '/tmp/report.csv', '/srv/import/report.csv', 0640)) throw new RuntimeException('SCP upload 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_send($session, '/tmp/status.txt', '/srv/import/report.csv', 0640)) throw new RuntimeException('SCP upload 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_send($session, '/tmp/snapshot.csv', '/srv/import/snapshot.csv', 0640)) throw new RuntimeException('SCP upload 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

Control local inputs, target paths and file permissions; an SCP upload does not validate file contents.

Comparison with Related Functions or Approaches

Common Beginner Mistakes

Key Takeaways

• ssh2_scp_send() uploads a local file over SCP to a remote destination.
• Control local inputs, target paths and file permissions; an SCP upload does not validate file contents.
• Use ssh2_sftp() if you need to work with remote streams and directories.

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