ENV vars and secrets have scalar values, and a string name (#4224)

Author: staabm

docs/api.md

@@ -382,8 +382,8 @@ run('echo \{{not_replaced}}'); // outputs: {{not_replaced}}
 | `$cwd` | `string` or `null` | Working directory for this run. Defaults to `{{working_path}}` (set by `cd()`). |
 | `$timeout` | `int` or `null` | Max runtime in seconds (default: `{{default_timeout}}`, 300; `null` disables). |
 | `$idleTimeout` | `int` or `null` | Max seconds without output before aborting. |
-| `$secrets` | `array` or `null` | Map of `%name%` placeholders to redacted values. |
-| `$env` | `array` or `null` | Environment variables: `run('echo $KEY', env: ['KEY' => 'value']);` |
+| `$secrets` | `array<string, scalar>` or `null` | Map of `%name%` placeholders to redacted values. |
+| `$env` | `array<string, scalar>` or `null` | Environment variables: `run('echo $KEY', env: ['KEY' => 'value']);` |
 | `$forceOutput` | `bool` or `null` | Print command output in real time. |
 | `$nothrow` | `bool` or `null` | Return output instead of throwing on non-zero exit. |
 
@@ -420,8 +420,8 @@ runLocally('npm run build', timeout: 600);
 | `$cwd` | `string` or `null` | Working directory for this run. Defaults to `{{working_path}}`. |
 | `$timeout` | `int` or `null` | Max runtime in seconds (default 300, `null` disables). |
 | `$idleTimeout` | `int` or `null` | Max seconds without output before aborting. |
-| `$secrets` | `array` or `null` | Map of `%name%` placeholders to redacted values. |
-| `$env` | `array` or `null` | Environment variables: `runLocally('echo $KEY', env: ['KEY' => 'value']);` |
+| `$secrets` | `array<string, scalar>` or `null` | Map of `%name%` placeholders to redacted values. |
+| `$env` | `array<string, scalar>` or `null` | Environment variables: `runLocally('echo $KEY', env: ['KEY' => 'value']);` |
 | `$forceOutput` | `bool` or `null` | Print command output in real time. |
 | `$nothrow` | `bool` or `null` | Return output instead of throwing on non-zero exit. |
 | `$shell` | `string` or `null` | Shell to run in. Default `bash -s`. |

src/Ssh/RunParams.php

@@ -4,6 +4,10 @@
 
 class RunParams
 {
+    /**
+     * @param array<string, scalar>|null $env
+     * @param array<string, scalar>|null $secrets
+     */
     public function __construct(
         public ?string  $shell = null,
         public ?string $cwd = null,
@@ -18,6 +22,9 @@ public function __construct(
         public ?array  $secrets = null,
     ) {}
 
+    /**
+     * @param array<string, scalar>|null $secrets
+     */
     public function with(
         #[\SensitiveParameter]
         ?array $secrets = null,

src/Support/helpers.php

@@ -67,6 +67,10 @@ function ($key, $value) {
     ));
 }
 
+/**
+ * @param array<string, scalar>|null $secrets
+ * @return string
+ */
 function replace_secrets(string $command, ?array $secrets): string
 {
     if (!empty($secrets)) {

src/functions.php

@@ -495,8 +495,8 @@ function within(string $path, callable $callback): mixed
  * @param string|null $cwd Working directory for this run. Defaults to `{{working_path}}` (set by `cd()`).
  * @param int|null $timeout Max runtime in seconds (default: `{{default_timeout}}`, 300; `null` disables).
  * @param int|null $idleTimeout Max seconds without output before aborting.
- * @param array|null $secrets Map of `%name%` placeholders to redacted values.
- * @param array|null $env Environment variables: `run('echo $KEY', env: ['KEY' => 'value']);`
+ * @param array<string, scalar>|null $secrets Map of `%name%` placeholders to redacted values.
+ * @param array<string, scalar>|null $env Environment variables: `run('echo $KEY', env: ['KEY' => 'value']);`
  * @param bool|null $forceOutput Print command output in real time.
  * @param bool|null $nothrow Return output instead of throwing on non-zero exit.
  * @throws RunException
@@ -581,8 +581,8 @@ function run(
  * @param string|null $cwd Working directory for this run. Defaults to `{{working_path}}`.
  * @param int|null $timeout Max runtime in seconds (default 300, `null` disables).
  * @param int|null $idleTimeout Max seconds without output before aborting.
- * @param array|null $secrets Map of `%name%` placeholders to redacted values.
- * @param array|null $env Environment variables: `runLocally('echo $KEY', env: ['KEY' => 'value']);`
+ * @param array<string, scalar>|null $secrets Map of `%name%` placeholders to redacted values.
+ * @param array<string, scalar>|null $env Environment variables: `runLocally('echo $KEY', env: ['KEY' => 'value']);`
  * @param bool|null $forceOutput Print command output in real time.
  * @param bool|null $nothrow Return output instead of throwing on non-zero exit.
  * @param string|null $shell Shell to run in. Default `bash -s`.