From 209c910f33e62f5c4f10a83d8597ea257825b036 Mon Sep 17 00:00:00 2001
From: Jonas Kattendick <kattendick@bde-software.com>
Date: Sat, 16 Aug 2025 21:48:01 +0200
Subject: [PATCH] feat: first impl

---
 composer.lock            |  18 +++++
 example.php              |  26 +++++++
 src/Child.php            |  49 ++++++++++++
 src/ChildStderr.php      |  10 +++
 src/ChildStdin.php       |  10 +++
 src/ChildStdout.php      |  10 +++
 src/Command.php          | 164 +++++++++++++++++++++++++++++++++++++++
 src/CommandException.php |  10 +++
 src/Output.php           |  15 ++++
 src/Stdio.php            |  32 ++++++++
 src/StdioFile.php        |  25 ++++++
 src/StdioPiped.php       |  16 ++++
 src/StreamReadable.php   |  28 +++++++
 src/StreamWritable.php   |  31 ++++++++
 14 files changed, 444 insertions(+)
 create mode 100644 composer.lock
 create mode 100644 example.php
 create mode 100644 src/Child.php
 create mode 100644 src/ChildStderr.php
 create mode 100644 src/ChildStdin.php
 create mode 100644 src/ChildStdout.php
 create mode 100644 src/Command.php
 create mode 100644 src/CommandException.php
 create mode 100644 src/Output.php
 create mode 100644 src/Stdio.php
 create mode 100644 src/StdioFile.php
 create mode 100644 src/StdioPiped.php
 create mode 100644 src/StreamReadable.php
 create mode 100644 src/StreamWritable.php

diff --git a/composer.lock b/composer.lock
new file mode 100644
index 0000000..23909e6
--- /dev/null
+++ b/composer.lock
@@ -0,0 +1,18 @@
+{
+    "_readme": [
+        "This file locks the dependencies of your project to a known state",
+        "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
+        "This file is @generated automatically"
+    ],
+    "content-hash": "e6871b52f4fe4ae525e588a0924fdf18",
+    "packages": [],
+    "packages-dev": [],
+    "aliases": [],
+    "minimum-stability": "stable",
+    "stability-flags": {},
+    "prefer-stable": false,
+    "prefer-lowest": false,
+    "platform": {},
+    "platform-dev": {},
+    "plugin-api-version": "2.6.0"
+}
diff --git a/example.php b/example.php
new file mode 100644
index 0000000..1933a4c
--- /dev/null
+++ b/example.php
@@ -0,0 +1,26 @@
+<?php
+
+use Nih\CommandBuilder\Command;
+use Nih\CommandBuilder\Stdio;
+
+require_once __DIR__ . '/vendor/autoload.php';
+
+$output = (new Command('echo'))
+    ->arg('-n')
+    ->arg('-')
+    ->arg("./ \$wow     '''/stdout.txt")
+    ->stderr(Stdio::null())
+    ->output();
+
+var_dump($output);
+
+$child = (new Command('/usr/bin/cat'))
+    ->stdin(Stdio::piped('r'))
+    ->spawn(shell: true);
+
+$child->stdin?->write('Hello, this is pretty cool.');
+$child->stdin?->close();
+
+$output = $child->output();
+
+var_dump($output);
diff --git a/src/Child.php b/src/Child.php
new file mode 100644
index 0000000..cd0eb4c
--- /dev/null
+++ b/src/Child.php
@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Nih\CommandBuilder;
+
+final class Child
+{
+    /**
+     * @param resource $proc The process handle.
+     */
+    public function __construct(
+        public readonly ?ChildStdin $stdin,
+        public readonly ?ChildStdout $stdout,
+        public readonly ?ChildStderr $stderr,
+        public $proc,
+    ) {
+    }
+
+    public function id(): int
+    {
+        $status = proc_get_status($this->proc);
+        return $status['pid'];
+    }
+
+    public function output(): Output
+    {
+        $stdout = $this->stdout?->getContents();
+        $stderr = $this->stderr?->getContents();
+        $code = proc_close($this->proc);
+
+        return new Output($stdout, $stderr, $code);
+    }
+
+    public function status(): int
+    {
+        return proc_close($this->proc);
+    }
+
+    public function wait(): void
+    {
+        proc_close($this->proc);
+    }
+
+    public function kill(): bool
+    {
+        return proc_terminate($this->proc, 10);
+    }
+}
diff --git a/src/ChildStderr.php b/src/ChildStderr.php
new file mode 100644
index 0000000..88e3937
--- /dev/null
+++ b/src/ChildStderr.php
@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Nih\CommandBuilder;
+
+final class ChildStderr
+{
+    use StreamReadable;
+}
diff --git a/src/ChildStdin.php b/src/ChildStdin.php
new file mode 100644
index 0000000..6e0676b
--- /dev/null
+++ b/src/ChildStdin.php
@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Nih\CommandBuilder;
+
+final class ChildStdin
+{
+    use StreamWritable;
+}
diff --git a/src/ChildStdout.php b/src/ChildStdout.php
new file mode 100644
index 0000000..023ac61
--- /dev/null
+++ b/src/ChildStdout.php
@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Nih\CommandBuilder;
+
+final class ChildStdout
+{
+    use StreamReadable;
+}
diff --git a/src/Command.php b/src/Command.php
new file mode 100644
index 0000000..8773613
--- /dev/null
+++ b/src/Command.php
@@ -0,0 +1,164 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Nih\CommandBuilder;
+
+use RuntimeException;
+use Stringable;
+use ValueError;
+
+final class Command
+{
+    public readonly string $command;
+
+    private array $args = [];
+    private ?array $envs = null;
+    private ?string $cwd = null;
+
+    private ?Stdio $stdin = null;
+    private ?Stdio $stdout = null;
+    private ?Stdio $stderr = null;
+
+    public function __construct(string $command)
+    {
+        if (strlen($command) === 0) {
+            throw new ValueError('Empty command');
+        }
+
+        $this->command = $command;
+        $this->args[] = $this->command;
+    }
+
+    public function arg(string|Stringable $arg): static
+    {
+        $this->args[] = (string) $arg;
+        return $this;
+    }
+
+    /**
+     * @param array<string|Stringable> $args
+     */
+    public function args(array $args): static
+    {
+        foreach ($args as $arg) {
+            $this->args[] = (string) $arg;
+        }
+
+        return $this;
+    }
+
+    public function cwd(string|Stringable $cwd): static
+    {
+        $this->cwd = (string) $cwd;
+        return $this;
+    }
+
+    public function env(string $var, string|Stringable $value): static
+    {
+        $this->envs[$var] = escapeshellarg((string) $value);
+        return $this;
+    }
+
+    /**
+     * @param array<string, string|Stringable> $envs
+     */
+    public function envs(array $envs): static
+    {
+        foreach ($envs as $var => $value) {
+            $this->envs[$var] = escapeshellarg((string) $value);
+        }
+
+        return $this;
+    }
+
+    public function stdin(Stdio $in): static
+    {
+        $this->stdin = $in;
+        return $this;
+    }
+
+    public function stdout(Stdio $out): static
+    {
+        $this->stdout = $out;
+        return $this;
+    }
+
+    public function stderr(Stdio $err): static
+    {
+        $this->stderr = $err;
+        return $this;
+    }
+
+    /**
+     * @param bool $shell Run the command with or without a shell
+     */
+    public function spawn(bool $shell = true): Child
+    {
+        $fd[0] = $this->stdin instanceof Stdio
+            ? $this->stdin->getDescriptorSpec()
+            : ['pipe', 'r'];
+
+        $fd[1] = $this->stdout instanceof Stdio
+            ? $this->stdout->getDescriptorSpec()
+            : ['pipe', 'w'];
+
+        $fd[2] = $this->stderr instanceof Stdio
+            ? $this->stderr->getDescriptorSpec()
+            : ['pipe', 'w'];
+
+        if ($shell) {
+            $command = implode(' ', array_map(escapeshellarg(...), $this->args));
+        } else if (is_executable($this->command)) {
+            $command = $this->args;
+        } else {
+            throw new CommandException(sprintf(
+                'Command "%s" is not executable',
+                $this->command,
+            ));
+        }
+
+        $proc = proc_open($command, $fd, $pipes, $this->cwd, $this->envs);
+        if ($proc === false) {
+            throw new RuntimeException();
+        }
+
+        $stdin = array_key_exists(0, $pipes)
+            ? new ChildStdin($pipes[0])
+            : null;
+
+        $stdout = array_key_exists(1, $pipes)
+            ? new ChildStdout($pipes[1])
+            : null;
+
+        $stderr = array_key_exists(2, $pipes)
+            ? new ChildStderr($pipes[2])
+            : null;
+
+        return new Child($stdin, $stdout, $stderr, $proc);
+    }
+
+    /**
+     * @param bool $shell Run the command with or without a shell
+     */
+    public function output(bool $shell = true): Output
+    {
+        return $this->spawn($shell)->output();
+    }
+
+    /**
+     * @param bool $shell Run the command with or without a shell
+     */
+    public function status(bool $shell = true): int
+    {
+        return $this->spawn($shell)->status();
+    }
+
+    /**
+     * @param bool $shell Run the command with or without a shell
+     */
+    public function wait(bool $shell = true): void
+    {
+        $this->spawn($shell)->wait();
+    }
+}
diff --git a/src/CommandException.php b/src/CommandException.php
new file mode 100644
index 0000000..0faec8c
--- /dev/null
+++ b/src/CommandException.php
@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Nih\CommandBuilder;
+
+use RuntimeException;
+
+final class CommandException extends RuntimeException
+{}
diff --git a/src/Output.php b/src/Output.php
new file mode 100644
index 0000000..c016c68
--- /dev/null
+++ b/src/Output.php
@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Nih\CommandBuilder;
+
+final class Output
+{
+    public function __construct(
+        public readonly ?string $stdout,
+        public readonly ?string $stderr,
+        public readonly int $code,
+    ) {
+    }
+}
diff --git a/src/Stdio.php b/src/Stdio.php
new file mode 100644
index 0000000..04f9a9e
--- /dev/null
+++ b/src/Stdio.php
@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Nih\CommandBuilder;
+
+use Stringable;
+
+abstract class Stdio
+{
+    abstract public function getDescriptorSpec(): array;
+
+    public static function file(string|Stringable $file, string $mode): self
+    {
+        return new StdioFile((string) $file, $mode);
+    }
+
+    public static function piped(string $mode): self
+    {
+        return new StdioPiped($mode);
+    }
+
+    public static function inherit(): null
+    {
+        return null;
+    }
+
+    public static function null(): self
+    {
+        return new StdioFile('/dev/null', 'a+');
+    }
+}
diff --git a/src/StdioFile.php b/src/StdioFile.php
new file mode 100644
index 0000000..9a0b2e4
--- /dev/null
+++ b/src/StdioFile.php
@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Nih\CommandBuilder;
+
+use ValueError;
+
+final class StdioFile extends Stdio
+{
+    public function __construct(
+        public readonly string $file,
+        public readonly string $mode,
+    ) {
+        match ($mode) {
+            'r', 'w', 'a', 'x', 'r+', 'w+', 'a+', 'x+' => null,
+            default => throw new ValueError('Invalid mode: ' . $mode),
+        };
+    }
+
+    public function getDescriptorSpec(): array
+    {
+        return ['file', $this->file, $this->mode];
+    }
+}
diff --git a/src/StdioPiped.php b/src/StdioPiped.php
new file mode 100644
index 0000000..16fde2f
--- /dev/null
+++ b/src/StdioPiped.php
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Nih\CommandBuilder;
+
+final class StdioPiped extends Stdio
+{
+    public function __construct(public readonly string $mode)
+    {}
+
+    public function getDescriptorSpec(): array
+    {
+        return ['pipe', $this->mode];
+    }
+}
diff --git a/src/StreamReadable.php b/src/StreamReadable.php
new file mode 100644
index 0000000..a63ec23
--- /dev/null
+++ b/src/StreamReadable.php
@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Nih\CommandBuilder;
+
+trait StreamReadable
+{
+    /**
+     * @param resource $stream
+     */
+    public function __construct(private $stream)
+    {
+    }
+
+    public function read(int $length): ?string
+    {
+        return fread($this->stream, $length) ?: null;
+    }
+
+    public function getContents(?int $length = null, int $offset = -1): ?string
+    {
+        $contents = stream_get_contents($this->stream, $length, $offset);
+        return $contents === false
+            ? null
+            : $contents;
+    }
+}
diff --git a/src/StreamWritable.php b/src/StreamWritable.php
new file mode 100644
index 0000000..3189b28
--- /dev/null
+++ b/src/StreamWritable.php
@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Nih\CommandBuilder;
+
+trait StreamWritable
+{
+    /**
+     * @param resource $stream
+     */
+    public function __construct(private $stream)
+    {
+    }
+
+    public function write(string $data, ?int $length = null): ?int
+    {
+        $bytes = fwrite($this->stream, $data, $length) ?: null;
+        return $bytes === false ? null : $bytes;
+    }
+
+    public function flush(): bool
+    {
+        return fflush($this->stream);
+    }
+
+    public function close(): bool
+    {
+        return fclose($this->stream);
+    }
+}