Refactor run and runLocally

Author: antonmedv

docs/UPGRADE.md

@@ -2,6 +2,10 @@
 
 ## Upgrade from 7.x to 8.x
 
+- `run()` and `runLocally()` doesn't accept `options` parameter anymore. Use named arguments instead.
+   - `no_throw` is now `nothrow`.
+   - `real_time_output` is now `forceOutput`.
+   - `idle_timeout` is now `idleTimeout`.
 
 ## Upgrade from 6.x to 7.x
 

docs/api.md

@@ -7,7 +7,7 @@
 ## host()
 
 ```php
-host(string ...$hostname)
+host(string ...$hostname): Host
 ```
 
 Defines a host or hosts.
@@ -24,13 +24,18 @@ task('test', function () {
 ```
 
 
-
 ## localhost()
 
 ```php
-localhost(string ...$hostnames)
+localhost(string ...$hostnames): Localhost
 ```
 
+Define a local host.
+Deployer will not connect to this host, but will execute commands locally instead.
+
+```php
+localhost('ci'); // Alias and hostname will be "ci".
+```
 
 
 ## currentHost()
@@ -85,7 +90,6 @@ import(__DIR__ . '/config/hosts.yaml');
 ```
 
 
-
 ## desc()
 
 ```php
@@ -98,7 +102,7 @@ Set task description.
 ## task()
 
 ```php
-task(string $name, $body = null): Task
+task(string $name, ?callable $body = null): Task
 ```
 
 Define a new task and save to tasks list.
@@ -110,12 +114,12 @@ Alternatively get a defined task.
 | Argument | Type | Comment |
 |---|---|---|
 | `$name` | `string` | Name of current task. |
-| `$body` | `callable():void` or `array` or `null` | Callable task, array of other tasks names or nothing to get a defined tasks |
+| `$body` | `?callable` | Callable task, array of other tasks names or nothing to get a defined tasks |
 
 ## before()
 
 ```php
-before(string $task, $do)
+before(string $task, string|callable $do): ?Task
 ```
 
 Call that task before specified task runs.
@@ -126,12 +130,12 @@ Call that task before specified task runs.
 | Argument | Type | Comment |
 |---|---|---|
 | `$task` | `string` | The task before $that should be run. |
-| `$do` | `string` or `callable():void` | The task to be run. |
+| `$do` | `string` or `callable` | The task to be run. |
 
 ## after()
 
 ```php
-after(string $task, $do)
+after(string $task, string|callable $do): ?Task
 ```
 
 Call that task after specified task runs.
@@ -142,12 +146,12 @@ Call that task after specified task runs.
 | Argument | Type | Comment |
 |---|---|---|
 | `$task` | `string` | The task after $that should be run. |
-| `$do` | `string` or `callable():void` | The task to be run. |
+| `$do` | `string` or `callable` | The task to be run. |
 
 ## fail()
 
 ```php
-fail(string $task, $do)
+fail(string $task, string|callable $do): ?Task
 ```
 
 Setup which task run on failure of $task.
@@ -159,7 +163,7 @@ When called multiple times for a task, previous fail() definitions will be overr
 | Argument | Type | Comment |
 |---|---|---|
 | `$task` | `string` | The task which need to fail so $that should be run. |
-| `$do` | `string` or `callable():void` | The task to be run. |
+| `$do` | `string` or `callable` | The task to be run. |
 
 ## option()
 
@@ -187,6 +191,11 @@ cd(string $path): void
 
 Change the current working directory.
 
+```php
+cd('~/myapp');
+run('ls'); // Will run `ls` in ~/myapp.
+```
+
 
 ## become()
 
@@ -210,7 +219,7 @@ $restore(); // revert back to the previous user
 ## within()
 
 ```php
-within(string $path, callable $callback)
+within(string $path, callable $callback): mixed
 ```
 
 Execute a callback within a specific directory and revert back to the initial working directory.
@@ -220,7 +229,15 @@ Execute a callback within a specific directory and revert back to the initial wo
 ## run()
 
 ```php
-run(string $command, ?array $options = [], ?int $timeout = null, ?int $idle_timeout = null, ?string $secret = null, ?array $env = null, ?bool $real_time_output = false, ?bool $no_throw = false): string
+run(
+    string  $command,
+    ?int    $timeout = null,
+    ?int    $idle_timeout = null,
+    ?string $secret = null,
+    ?array  $env = null,
+    ?bool   $real_time_output = false,
+    ?bool   $no_throw = false,
+): string 
 ```
 
 Executes given command on remote host.
@@ -245,7 +262,6 @@ run("echo $path");
 | Argument | Type | Comment |
 |---|---|---|
 | `$command` | `string` | Command to run on remote host. |
-| `$options` | `array` or `null` | Array of options will override passed named arguments. |
 | `$timeout` | `int` or `null` | Sets the process timeout (max. runtime). The timeout in seconds (default: 300 sec; see {{default_timeout}}, `null` to disable). |
 | `$idle_timeout` | `int` or `null` | Sets the process idle timeout (max. time since last output) in seconds. |
 | `$secret` | `string` or `null` | Placeholder `%secret%` can be used in command. Placeholder will be replaced with this value and will not appear in any logs. |

recipe/deploy/update_code.php

@@ -88,7 +88,7 @@
     start:
     // Clone the repository to a bare repo.
     run("[ -d $bare ] || mkdir -p $bare");
-    run("[ -f $bare/HEAD ] || $git clone --mirror $repository $bare 2>&1", ['env' => $env]);
+    run("[ -f $bare/HEAD ] || $git clone --mirror $repository $bare 2>&1", env: $env);
 
     cd($bare);
 
@@ -99,7 +99,7 @@
         goto start;
     }
 
-    run("$git remote update 2>&1", ['env' => $env]);
+    run("$git remote update 2>&1", env: $env);
 
 
     // Copy to release_path.
@@ -108,7 +108,7 @@
     } elseif (get('update_code_strategy') === 'clone') {
         cd('{{release_path}}');
         run("$git clone -l $bare .");
-        run("$git remote set-url origin $repository", ['env' => $env]);
+        run("$git remote set-url origin $repository", env: $env);
         run("$git checkout --force $target");
     } else {
         throw new ConfigurationException(parse("Unknown `update_code_strategy` option: {{update_code_strategy}}."));

recipe/provision.php

@@ -124,22 +124,22 @@
     set('remote_user', get('provision_user'));
 
     // PHP
-    run('apt-add-repository ppa:ondrej/php -y', ['env' => ['DEBIAN_FRONTEND' => 'noninteractive']]);
+    run('apt-add-repository ppa:ondrej/php -y', env: ['DEBIAN_FRONTEND' => 'noninteractive']);
 
     // Caddy
     run("curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor --yes -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg");
     run("curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' > /etc/apt/sources.list.d/caddy-stable.list");
 
     // Update
-    run('apt-get update', ['env' => ['DEBIAN_FRONTEND' => 'noninteractive']]);
+    run('apt-get update', env: ['DEBIAN_FRONTEND' => 'noninteractive']);
 })
     ->oncePerNode()
     ->verbose();
 
 desc('Upgrades all packages');
 task('provision:upgrade', function () {
     set('remote_user', get('provision_user'));
-    run('apt-get upgrade -y', ['env' => ['DEBIAN_FRONTEND' => 'noninteractive'], 'timeout' => 900]);
+    run('apt-get upgrade -y', env: ['DEBIAN_FRONTEND' => 'noninteractive'], timeout: 900);
 })
     ->oncePerNode()
     ->verbose();
@@ -174,7 +174,7 @@
         'uuid-runtime',
         'whois',
     ];
-    run('apt-get install -y ' . implode(' ', $packages), ['env' => ['DEBIAN_FRONTEND' => 'noninteractive'], 'timeout' => 900]);
+    run('apt-get install -y ' . implode(' ', $packages), env: ['DEBIAN_FRONTEND' => 'noninteractive'], timeout: 900);
 })
     ->verbose()
     ->oncePerNode();

recipe/provision/databases.php

@@ -38,9 +38,9 @@
 
 desc('Provision MySQL');
 task('provision:mysql', function () {
-    run('apt-get install -y mysql-server', ['env' => ['DEBIAN_FRONTEND' => 'noninteractive'], 'timeout' => 900]);
-    run("mysql --user=\"root\" -e \"CREATE USER IF NOT EXISTS '{{db_user}}'@'0.0.0.0' IDENTIFIED BY '%secret%';\"", ['secret' => get('db_password')]);
-    run("mysql --user=\"root\" -e \"CREATE USER IF NOT EXISTS '{{db_user}}'@'%' IDENTIFIED BY '%secret%';\"", ['secret' => get('db_password')]);
+    run('apt-get install -y mysql-server', env: ['DEBIAN_FRONTEND' => 'noninteractive'], timeout: 900);
+    run("mysql --user=\"root\" -e \"CREATE USER IF NOT EXISTS '{{db_user}}'@'0.0.0.0' IDENTIFIED BY '%secret%';\"", secret: get('db_password'));
+    run("mysql --user=\"root\" -e \"CREATE USER IF NOT EXISTS '{{db_user}}'@'%' IDENTIFIED BY '%secret%';\"", secret: get('db_password'));
     run("mysql --user=\"root\" -e \"GRANT ALL PRIVILEGES ON *.* TO '{{db_user}}'@'0.0.0.0' WITH GRANT OPTION;\"");
     run("mysql --user=\"root\" -e \"GRANT ALL PRIVILEGES ON *.* TO '{{db_user}}'@'%' WITH GRANT OPTION;\"");
     run("mysql --user=\"root\" -e \"FLUSH PRIVILEGES;\"");
@@ -49,9 +49,9 @@
 
 desc('Provision MariaDB');
 task('provision:mariadb', function () {
-    run('apt-get install -y mariadb-server', ['env' => ['DEBIAN_FRONTEND' => 'noninteractive'], 'timeout' => 900]);
-    run("mysql --user=\"root\" -e \"CREATE USER IF NOT EXISTS '{{db_user}}'@'0.0.0.0' IDENTIFIED BY '%secret%';\"", ['secret' => get('db_password')]);
-    run("mysql --user=\"root\" -e \"CREATE USER IF NOT EXISTS '{{db_user}}'@'%' IDENTIFIED BY '%secret%';\"", ['secret' => get('db_password')]);
+    run('apt-get install -y mariadb-server', env: ['DEBIAN_FRONTEND' => 'noninteractive'], timeout: 900);
+    run("mysql --user=\"root\" -e \"CREATE USER IF NOT EXISTS '{{db_user}}'@'0.0.0.0' IDENTIFIED BY '%secret%';\"", secret: get('db_password'));
+    run("mysql --user=\"root\" -e \"CREATE USER IF NOT EXISTS '{{db_user}}'@'%' IDENTIFIED BY '%secret%';\"", secret: get('db_password'));
     run("mysql --user=\"root\" -e \"GRANT ALL PRIVILEGES ON *.* TO '{{db_user}}'@'0.0.0.0' WITH GRANT OPTION;\"");
     run("mysql --user=\"root\" -e \"GRANT ALL PRIVILEGES ON *.* TO '{{db_user}}'@'%' WITH GRANT OPTION;\"");
     run("mysql --user=\"root\" -e \"FLUSH PRIVILEGES;\"");
@@ -60,8 +60,8 @@
 
 desc('Provision PostgreSQL');
 task('provision:postgresql', function () {
-    run('apt-get install -y postgresql postgresql-contrib', ['env' => ['DEBIAN_FRONTEND' => 'noninteractive'], 'timeout' => 900]);
+    run('apt-get install -y postgresql postgresql-contrib', env: ['DEBIAN_FRONTEND' => 'noninteractive'], timeout: 900);
     run("sudo -u postgres psql <<< $'CREATE DATABASE {{db_name}};'");
-    run("sudo -u postgres psql <<< $'CREATE USER {{db_user}} WITH ENCRYPTED PASSWORD \'%secret%\';'", ['secret' => get('db_password')]);
+    run("sudo -u postgres psql <<< $'CREATE USER {{db_user}} WITH ENCRYPTED PASSWORD \'%secret%\';'", secret: get('db_password'));
     run("sudo -u postgres psql <<< $'GRANT ALL PRIVILEGES ON DATABASE {{db_name}} TO {{db_user}};'");
 });

recipe/provision/php.php

@@ -33,7 +33,7 @@
         "php$version-xml",
         "php$version-zip",
     ];
-    run('apt-get install -y ' . implode(' ', $packages), ['env' => ['DEBIAN_FRONTEND' => 'noninteractive']]);
+    run('apt-get install -y ' . implode(' ', $packages), env: ['DEBIAN_FRONTEND' => 'noninteractive']);
 
     // Configure PHP-CLI
     run("sed -i 's/error_reporting = .*/error_reporting = E_ALL/' /etc/php/$version/cli/php.ini");

recipe/provision/user.php

@@ -32,8 +32,8 @@
         // Make color prompt.
         run("sed -i 's/#force_color_prompt=yes/force_color_prompt=yes/' /home/deployer/.bashrc");
 
-        $password = run("mkpasswd -m sha-512 '%secret%'", ['secret' => get('sudo_password')]);
-        run("usermod --password '%secret%' deployer", ['secret' => $password]);
+        $password = run("mkpasswd -m sha-512 '%secret%'", secret: get('sudo_password'));
+        run("usermod --password '%secret%' deployer", secret: $password);
 
         // Copy root public key to deployer user so user can login without password.
         run('cp /root/.ssh/authorized_keys /home/deployer/.ssh/authorized_keys');
@@ -82,9 +82,5 @@
         return;
     }
 
-    run('echo "$PUBLIC_KEY" >> /home/deployer/.ssh/authorized_keys', [
-        'env' => [
-            'PUBLIC_KEY' => $publicKeyContent,
-        ],
-    ]);
+    run('echo "$PUBLIC_KEY" >> /home/deployer/.ssh/authorized_keys', env: ['PUBLIC_KEY' => $publicKeyContent]);
 });

recipe/provision/website.php

@@ -4,8 +4,6 @@
 
 namespace Deployer;
 
-use function Deployer\Support\escape_shell_argument;
-
 set('domain', function () {
     return ask(' Domain: ', get('hostname'));
 });
@@ -40,7 +38,7 @@
 
     if (test('[ -f Caddyfile ]')) {
         run("echo $'$caddyfile' > Caddyfile.new");
-        $diff = run('diff -U5 --color=always Caddyfile Caddyfile.new', ['no_throw' => true]);
+        $diff = run('diff -U5 --color=always Caddyfile Caddyfile.new', nothrow: true);
         if (empty($diff)) {
             run('rm Caddyfile.new');
         } else {

src/Command/RunCommand.php

@@ -72,10 +72,11 @@ protected function execute(Input $input, Output $output): int
                     cd($path);
                 }
             }
-            run($command, [
-                'real_time_output' => true,
-                'timeout' => intval($input->getOption('timeout')),
-            ]);
+            run(
+                $command,
+                timeout: intval($input->getOption('timeout')),
+                forceOutput: true,
+            );
         });
 
         foreach ($hosts as $host) {

src/Documentation/ApiGen.php

@@ -21,6 +21,7 @@ public function parse(string $source): void
     {
         $comment = '';
         $params = '';
+        $signature = '';
 
         $source = str_replace("\r\n", "\n", $source);
 
@@ -34,7 +35,7 @@ public function parse(string $source): void
                     }
                     if (str_starts_with($line, 'function')) {
                         $signature = preg_replace('/^function\s+/', '', $line);
-                        $funcName = preg_replace('/\(.+$/', '', $signature);
+                        $funcName = preg_replace('/\(.*$/', '', $signature);
                         $this->fns[] = [
                             'comment' => $comment,
                             'params' => $params,
@@ -43,7 +44,12 @@ public function parse(string $source): void
                         ];
                         $comment = '';
                         $params = '';
-                        break;
+
+                        if (str_ends_with($signature, '(')) {
+                            $state = 'params';
+                        } else {
+                            $signature = '';
+                        }
                     }
                     break;
 
@@ -68,6 +74,16 @@ public function parse(string $source): void
                     }
                     $comment .= preg_replace('/^\s\*\s?/', '', $line) . "\n";
                     break;
+
+                case 'params':
+                    if (preg_match('/^\).+\{$/', $line, $matches)) {
+                        $signature .= "\n" . preg_replace('/\{$/', '', $line);
+                        $this->fns[count($this->fns) - 1]['signature'] = $signature;
+                        $state = 'root';
+                    } else {
+                        $signature .= "\n" . $line;
+                    }
+                    break;
             }
         }
     }