azjezz · azjezz · May 7, 2022 · Feb 3, 2022
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -67,3 +67,7 @@
 * **BC** - `Psl\Result\ResultInterface::getException()` method has been renamed to `Psl\Result\ResultInterface::getThrowable()`
 * **BC** - `Psl\Result\wrap` function now catches all `Throwable`s instead of only `Exception`s
 * introduced a new `Psl\Result\reflect` function
+* **BC** - `Psl\Shell\escape_argument` function has been removed, `Shell\execute` arguments are now always escaped.
+* **BC** - `$escape_arguments` argument of `Shell\execute` function has been removed.
+* introduced a new `Psl\Shell\ErrorOutputBehavior` enum
+* added a new `$error_output_behavior` argument to `Shell\execute` function, which can be used to return the command error output content, as well as the standard output content.
diff --git a/config/.phpcs.xml b/config/.phpcs.xml
@@ -15,6 +15,7 @@
     <exclude-pattern>*/src/Psl/Hash/Hmac/Algorithm.php</exclude-pattern>
     <exclude-pattern>*/src/Psl/OS/OperatingSystemFamily.php</exclude-pattern>
     <exclude-pattern>*/src/Psl/Password/Algorithm.php</exclude-pattern>
+    <exclude-pattern>*/src/Psl/Shell/ErrorOutputBehavior.php</exclude-pattern>
 
     <arg name="basepath" value="."/>
     <arg name="colors"/>

diff --git a/docs/component/shell.md b/docs/component/shell.md
@@ -12,7 +12,11 @@
 
 #### `Functions`
 
-- [escape_argument](./../../src/Psl/Shell/escape_argument.php#L17)
 - [execute](./../../src/Psl/Shell/execute.php#L42)
+- [unpack](./../../src/Psl/Shell/unpack.php#L20)
+
+#### `Enums`
+
+- [ErrorOutputBehavior](./../../src/Psl/Shell/ErrorOutputBehavior.php#L7)
 
 
diff --git a/src/Psl/Internal/Loader.php b/src/Psl/Internal/Loader.php
@@ -377,8 +377,9 @@ final class Loader
         'Psl\Encoding\Base64\decode',
         'Psl\Encoding\Hex\encode',
         'Psl\Encoding\Hex\decode',
-        'Psl\Shell\escape_argument',
         'Psl\Shell\execute',
+        'Psl\Shell\unpack',
+        'Psl\Shell\Internal\escape_argument',
         'Psl\Html\encode',
         'Psl\Html\encode_special_characters',
         'Psl\Html\decode',
@@ -634,6 +635,7 @@ final class Loader
         'Psl\Shell\Exception\RuntimeException',
         'Psl\Shell\Exception\PossibleAttackException',
         'Psl\Shell\Exception\TimeoutException',
+        'Psl\Shell\Exception\InvalidArgumentException',
         'Psl\Math\Exception\ArithmeticException',
         'Psl\Math\Exception\DivisionByZeroException',
         'Psl\Filesystem\Exception\RuntimeException',
@@ -743,6 +745,7 @@ final class Loader
         'Psl\Hash\Hmac\Algorithm',
         'Psl\OS\OperatingSystemFamily',
         'Psl\Password\Algorithm',
+        'Psl\Shell\ErrorOutputBehavior'
     ];
 
     public const TYPE_CONSTANTS = 1;

diff --git a/src/Psl/Shell/ErrorOutputBehavior.php b/src/Psl/Shell/ErrorOutputBehavior.php
@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Shell;
+
+enum ErrorOutputBehavior {
+    /**
+     * Discard the standard error output.
+     *
+     * Example:
+     *
+     *      $stdout = Shell\execute('cmd', ['arg1', 'arg2'], error_output_behavior: ErrorOutputBehavior::Discard);
+     */
+    case Discard;
+
+    /**
+     * Append the standard error output content to the standard output content.
+     *
+         * Example:
+     *
+     *      $stdout_followed_by_stderr = Shell\execute('cmd', ['arg1', 'arg2'], error_output_behavior: ErrorOutputBehavior::Append);
+     */
+    case Append;
+
+    /**
+     * Prepend the standard error output content to the standard output content.
+     *
+     * Example:
+     *
+     *      $stderr_followed_by_stdout = Shell\execute('cmd', ['arg1', 'arg2'], error_output_behavior: ErrorOutputBehavior::Prepend);
+     */
+    case Prepend;
+
+    /**
+     * Replace the standard output content with the standard error output content.
+     *
+     * Example:
+     *
+     *      $stderr = Shell\execute('cmd', ['arg1', 'arg2'], error_output_behavior: ErrorOutputBehavior::Replace);
+     */
+    case Replace;
+
+    /**
+     * Pack the standard output content with the standard error output content, enabling
+     * you to split them later on, using `Shell\unpack`.
+     *
+     * Example:
+     *
+     *      $result = Shell\execute('cmd', ['arg1', 'arg2'], error_output_behavior: ErrorOutputBehavior::Packed);
+     *      [$stdout, $stderr] = Shell\unpack($result);
+     *
+     * @note The packing format is not guaranteed to be BC, you should always use `Shell\unpack` instead of attempting to unpack the result manually.
+     */
+    case Packed;
+}
diff --git a/src/Psl/Shell/Exception/InvalidArgumentException.php b/src/Psl/Shell/Exception/InvalidArgumentException.php
@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Shell\Exception;
+
+use Psl\Exception;
+
+final class InvalidArgumentException extends Exception\InvalidArgumentException implements ExceptionInterface
+{
+}
diff --git a/src/Psl/Shell/escape_argument.php → src/Psl/Shell/Internal/escape_argument.php b/src/Psl/Shell/escape_argument.php → src/Psl/Shell/Internal/escape_argument.php
@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace P
B422
sl\Shell;
+namespace Psl\Shell\Internal;
 
 use Psl\Regex;
 use Psl\Str\Byte;
@@ -13,6 +13,8 @@
  * Escape a string to be used as a shell argument.
  *
  * @psalm-taint-escape shell
+ *
+ * @internal
  */
 function escape_argument(string $argument): string
 {

diff --git a/src/Psl/Shell/execute.php b/src/Psl/Shell/execute.php
@@ -16,6 +16,7 @@
 use Psl\Vec;
 
 use function is_resource;
+use function pack;
 use function proc_close;
 use function proc_open;
 use function strpbrk;
@@ -30,7 +31,6 @@
  *                                                 use the default value ( the current directory )
  * @param array<string, string> $environment A dict with the environment variables for the command that
  *                                           will be run.
- * @param bool $escape_arguments If set to true ( default ), all $arguments will be escaped using `escape_argument`.
  *
  * @psalm-taint-sink shell $command
  *
@@ -44,23 +44,10 @@ function execute(
     array   $arguments = [],
     ?string $working_directory = null,
     array   $environment = [],
-    bool    $escape_arguments = true,
+    ErrorOutputBehavior $error_output_behavior = ErrorOutputBehavior::Discard,
     ?float  $timeout = null
 ): string {
-    if ($escape_arguments) {
-        $arguments = Vec\map(
-            $arguments,
-            /**
-             * @param string $argument
-             *
-             * @return string
-             *
-             * @pure
-             */
-            static fn(string $argument): string => escape_argument($argument)
-        );
-    }
-
+    $arguments = Vec\map($arguments, Internal\escape_argument(...));
     $commandline = Str\join([$command, ...$arguments], ' ');
 
     /** @psalm-suppress MissingThrowsDocblock - safe ( $offset is within-of-bounds ) */
@@ -201,5 +188,30 @@ static function (array $m) use (
         throw new Exception\FailedExecutionException($commandline, $stdout_content, $stderr_content, $code);
     }
 
-    return $stdout_content;
+    if (ErrorOutputBehavior::Packed === $error_output_behavior) {
+        $result = '';
+        $stdout_length = Str\Byte\length($stdout_content);
+        $stderr_length = Str\Byte\length($stderr_content);
+
+        if ($stdout_length) {
+            $stdout_header = pack('C1N1', 1, $stdout_length);
+
+            $result .= $stdout_header . $stdout_content;
+        }
+
+        if ($stderr_length) {
+            $stderr_header = pack('C1N1', 2, $stderr_length);
+
+            $result .= $stderr_header . $stderr_content;
+        }
+
+        return $result;
+    }
+
+    return match ($error_output_behavior) {
+        ErrorOutputBehavior::Prepend => $stderr_content . $stdout_content,
+        ErrorOutputBehavior::Append => $stdout_content . $stderr_content,
+        ErrorOutputBehavior::Replace => $stderr_content,
+        ErrorOutputBehavior::Packed, ErrorOutputBehavior::Discard => $stdout_content,
+    };
 }
diff --git a/src/Psl/Shell/unpack.php b/src/Psl/Shell/unpack.php
@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Shell;
+
+use Psl\Str;
+
+use function unpack as byte_unpack;
+
+/**
+ * Unpack the result of `Shell\execute()` when using `ErrorOutputBehavior::Packed` error output behavior.
+ *
+ * @param string $content
+ *
+ * @throws Exception\InvalidArgumentException If $content is invalid.
+ *
+ * @return array{0: string, 1: string} - A tuple, containing the standard output content as it's first element, followed by the standard error output content.
+ */
+function unpack(string $content): array
+{
+    $result = ['', ''];
+    while ($content !== '') {
+        if (Str\Byte\length($content) < 5) {
+            throw new Exception\InvalidArgumentException('$content contains an invalid header value.');
+        }
+
+        $headers = byte_unpack('C1type/N1size', Str\Byte\slice($content, 0, 5));
+        /** @var int<0, max> $type */
+        $type = (int) $headers['type'];
+        /** @var int<0, max> $size */
+        $size = (int) $headers['size'];
+
+        if ($size > (Str\Byte\length($content) - 5)) {
+            throw new Exception\InvalidArgumentException('$content contains an invalid header value.');
+        }
+
+        $chunk = Str\Byte\slice($content, 5, $size);
+        $content = Str\Byte\slice($content, $size + 5);
+
+        if ($type === 1) {
+            $result[0] .= $chunk;
+        } elseif ($type === 2) {
+            $result[1] .= $chunk;
+        } else {
+            throw new Exception\InvalidArgumentException('$content contains an invalid header value.');
+        }
+    }
+
+    return $result;
+}
diff --git a/tests/unit/Shell/EscapeArgumentTest.php b/tests/unit/Shell/EscapeArgumentTest.php
diff --git a/tests/unit/Shell/ExecuteTest.php b/tests/unit/Shell/ExecuteTest.php
@@ -91,4 +91,42 @@ public function testItThrowsWhenWorkingDirectoryDoesntExist(): void
 
         Shell\execute(PHP_BINARY, ['-r', 'echo getcwd();'], $dir);
     }
+
+    public function testErrorOutputIsDiscarded(): void
+    {
+        $result = Shell\execute(PHP_BINARY, ['-r', 'fwrite(STDOUT, "hello"); fwrite(STDERR, " world");']);
+
+        static::assertSame('hello', $result);
+    }
+
+    public function testErrorOutputIsAppended(): void
+    {
+        $result = Shell\execute(PHP_BINARY, ['-r', 'fwrite(STDOUT, "hello"); fwrite(STDERR, " world");'], error_output_behavior: Shell\ErrorOutputBehavior::Append);
+
+        static::assertSame('hello world', $result);
+    }
+
+    public function testErrorOutputIsPrepended(): void
+    {
+        $result = Shell\execute(PHP_BINARY, ['-r', 'fwrite(STDOUT, "hello"); fwrite(STDERR, " world");'], error_output_behavior: Shell\ErrorOutputBehavior::Prepend);
+
+        static::assertSame(' worldhello', $result);
+    }
+
+    public function testErrorOutputIsReplacingStandardOutput(): void
+    {
+        $result = Shell\execute(PHP_BINARY, ['-r', 'fwrite(STDOUT, "hello"); fwrite(STDERR, " world");'], error_output_behavior: Shell\ErrorOutputBehavior::Replace);
+
+        static::assertSame(' world', $result);
+    }
+
+    public function testErrorOutputIsPacked(): void
+    {
+        $result = Shell\execute(PHP_BINARY, ['-r', 'fwrite(STDOUT, "hello"); fwrite(STDERR, " world");'], error_output_behavior: Shell\ErrorOutputBehavior::Packed);
+
+        [$stdout, $stderr] = Shell\unpack($result);
+
+        static::assertSame('hello', $stdout);
+        static::assertSame(' world', $stderr);
+    }
 }