Add SSH upload and download functions

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Not released yet
 
+* Add `ssh_upload()` and `ssh_download()` functions to upload/download files via SSH
+* Rename `ssh()` to `ssh_run()`
+
 ## 0.9.1 (2023-10-09)
 
 * Fix castor application version

bin/generate-tests.php

@@ -27,6 +27,8 @@
     'watch:parallel-change',
     'watch:stop',
     'ssh:ls',
+    'ssh:upload',
+    'ssh:download',
     // Not examples
     'castor:phar:build',
     'castor:phar:darwin',

examples/ssh.php

@@ -4,13 +4,26 @@
 
 use Castor\Attribute\AsTask;
 
-use function Castor\ssh;
+use function Castor\ssh_download;
+use function Castor\ssh_run;
+use function Castor\ssh_upload;
 
 #[AsTask(description: 'Lists content of /var/www directory on the remote server')]
 function ls(): void
 {
-    // List content of /var/www directory on the remote server
-    ssh('ls -alh', host: 'server-1.example.com', user: 'debian', sshOptions: [
+    ssh_run('ls -alh', host: 'server-1.example.com', user: 'debian', sshOptions: [
         'port' => 2222,
     ], path: '/var/www');
 }
+
+#[AsTask(description: 'Uploads a file to the remote server')]
+function upload(): void
+{
+    ssh_upload('/tmp/test.html', '/var/www/index.html', host: 'server-1.example.com', user: 'debian');
+}
+
+#[AsTask(description: 'Downloads a file from the remote server')]
+function download(): void
+{
+    ssh_download('/tmp/test.html', '/var/www/index.html', host: 'server-1.example.com', user: 'debian');
+}

phpstan-baseline.neon

@@ -19,3 +19,8 @@ parameters:
 			message: "#^Function Castor\\\\get_exit_code\\(\\) has parameter \\$args with no type specified\\.$#"
 			count: 1
 			path: src/functions.php
+
+		-
+			message: "#^Function Castor\\\\ssh\\(\\) has parameter \\$args with no type specified\\.$#"
+			count: 1
+			path: src/functions.php

src/Console/Application.php

@@ -122,7 +122,7 @@ private function initializeApplication(InputInterface $input): array
         if ($contextNames) {
             $this->getDefinition()->addOption(new InputOption(
                 'context',
-                '_complete' === $input->getFirstArgument() ? null : 'c',
+                '_complete' === $input->getFirstArgument() || 'list' === $input->getFirstArgument() ? null : 'c',
                 InputOption::VALUE_REQUIRED,
                 sprintf('The context to use (%s)', implode('|', $contextNames)),
                 $this->contextRegistry->getDefault(),

src/functions.php

@@ -295,7 +295,7 @@ function get_exit_code(...$args): int
  *     'password_authentication'?: bool,
  * } $sshOptions
  */
-function ssh(
+function ssh_run(
     string $command,
     string $host,
     string $user,
@@ -306,6 +306,125 @@ function ssh(
     bool $notify = null,
     float $timeout = null,
 ): Process {
+    $ssh = ssh_configuration($host, $user, $sshOptions);
+
+    if ($path) {
+        $command = sprintf('cd %s && %s', $path, $command);
+    }
+
+    return run(
+        $ssh->getExecuteCommand($command),
+        environment: [],
+        tty: false,
+        pty: false,
+        timeout: $timeout,
+        quiet: $quiet,
+        allowFailure: $allowFailure,
+        notify: $notify
+    );
+}
+
+function ssh(...$args): Process
+{
+    trigger_deprecation('jolicode/castor', '0.10', 'The "%s()" function is deprecated, use "Castor\%s()" instead.', __FUNCTION__, 'ssh_run');
+
+    return ssh_run(...$args);
+}
+
+/**
+ * This function is considered experimental and may change in the future.
+ *
+ * @param array{
+ *     'port'?: int,
+ *     'path_private_key'?: string,
+ *     'jump_host'?: string,
+ *     'multiplexing_control_path'?: string,
+ *     'multiplexing_control_persist'?: string,
+ *     'enable_strict_check'?: bool,
+ *     'password_authentication'?: bool,
+ * } $sshOptions
+ */
+function ssh_upload(
+    string $sourcePath,
+    string $destinationPath,
+    string $host,
+    string $user,
+    array $sshOptions = [],
+    bool $quiet = null,
+    bool $allowFailure = null,
+    bool $notify = null,
+    float $timeout = null,
+): Process {
+    $ssh = ssh_configuration($host, $user, $sshOptions);
+
+    return run(
+        $ssh->getUploadCommand($sourcePath, $destinationPath),
+        environment: [],
+        tty: false,
+        pty: false,
+        timeout: $timeout,
+        quiet: $quiet,
+        allowFailure: $allowFailure,
+        notify: $notify
+    );
+}
+
+/**
+ * This function is considered experimental and may change in the future.
+ *
+ * @param array{
+ *     'port'?: int,
+ *     'path_private_key'?: string,
+ *     'jump_host'?: string,
+ *     'multiplexing_control_path'?: string,
+ *     'multiplexing_control_persist'?: string,
+ *     'enable_strict_check'?: bool,
+ *     'password_authentication'?: bool,
+ * } $sshOptions
+ */
+function ssh_download(
+    string $sourcePath,
+    string $destinationPath,
+    string $host,
+    string $user,
+    array $sshOptions = [],
+    bool $quiet = null,
+    bool $allowFailure = null,
+    bool $notify = null,
+    float $timeout = null,
+): Process {
+    $ssh = ssh_configuration($host, $user, $sshOptions);
+
+    return run(
+        $ssh->getDownloadCommand($sourcePath, $destinationPath),
+        environment: [],
+        tty: false,
+        pty: false,
+        timeout: $timeout,
+        quiet: $quiet,
+        allowFailure: $allowFailure,
+        notify: $notify
+    );
+}
+
+/**
+ * @param array{
+ *     'port'?: int,
+ *     'path_private_key'?: string,
+ *     'jump_host'?: string,
+ *     'multiplexing_control_path'?: string,
+ *     'multiplexing_control_persist'?: string,
+ *     'enable_strict_check'?: bool,
+ *     'password_authentication'?: bool,
+ * } $sshOptions
+ *
+ * @internal
+ */
+function ssh_configuration(
+    string $host,
+    string $user,
+    array $sshOptions = [],
+): Ssh {
     $ssh = Ssh::create($user, $host, $sshOptions['port'] ?? null);
 
     if ($sshOptions['path_private_key'] ?? false) {
@@ -323,20 +442,8 @@ function ssh(
     if ($sshOptions['password_authentication'] ?? false) {
         $sshOptions['password_authentication'] ? $ssh->enablePasswordAuthentication() : $ssh->disableStrictHostKeyChecking();
     }
-    if ($path) {
-        $command = sprintf('cd %s && %s', $path, $command);
-    }
 
-    return run(
-        $ssh->getExecuteCommand($command),
-        environment: [],
-        tty: false,
-        pty: false,
-        timeout: $timeout,
-        quiet: $quiet,
-        allowFailure: $allowFailure,
-        notify: $notify
-    );
+    return $ssh;
 }
 
 function notify(string $message): void

tests/Examples/ListTest.php.output.txt

@@ -50,7 +50,9 @@ run:with-process-helper                              Run a sub-process and displ
 shell:bash                                           Runs a bash
 shell:sh                                             Runs a sh
 signal:sigusr2                                       Captures SIGUSR2 signal
+ssh:download                                         Downloads a file from the remote server
 ssh:ls                                               Lists content of /var/www directory on the remote server
+ssh:upload                                           Uploads a file to the remote server
 watch:fs-change                                      Watches on filesystem changes
 watch:parallel-change                                Watches on filesystem changes with 2 watchers in parallel
 watch:stop                                           Watches on filesystem changes and stop after first change