added Process

Author: dg

src/Utils/Process.php

@@ -46,3 +46,19 @@ class RegexpException extends \Exception
 class AssertionException extends \Exception
 {
 }
+
+
+/**
+ * The process failed to run successfully.
+ */
+class ProcessFailedException extends \RuntimeException
+{
+}
+
+
+/**
+ * The process execution exceeded its timeout limit.
+ */
+class ProcessTimeoutException extends \RuntimeException
+{
+}

src/Utils/exceptions.php

@@ -0,0 +1,180 @@
+<?php declare(strict_types=1);
+
+use Nette\Utils\Helpers;
+use Nette\Utils\Process;
+use Nette\Utils\ProcessFailedException;
+use Nette\Utils\ProcessTimeoutException;
+use Tester\Assert;
+
+require __DIR__ . '/../bootstrap.php';
+
+
+// Process execution - success
+
+test('run executable successfully', function () {
+	$process = Process::runExecutable(PHP_BINARY, ['-r', 'echo "hello";']);
+	Assert::true($process->isSuccess());
+	Assert::same(0, $process->getExitCode());
+	Assert::same('hello', $process->getStdOutput());
+	Assert::same('', $process->getStdError());
+});
+
+test('run command successfully', function () {
+	$process = Process::runCommand('echo hello');
+	Assert::true($process->isSuccess());
+	Assert::same(0, $process->getExitCode());
+	Assert::same('hello' . PHP_EOL, $process->getStdOutput());
+	Assert::same('', $process->getStdError());
+});
+
+
+// Process execution - errors
+
+test('run executable with error', function () {
+	$process = Process::runExecutable(PHP_BINARY, ['-r', 'exit(1);']);
+	Assert::false($process->isSuccess());
+	Assert::same(1, $process->getExitCode());
+});
+
+test('run executable ensure success throws exception on error', function () {
+	Assert::exception(
+		fn() => Process::runExecutable(PHP_BINARY, ['-r', 'exit(1);'])->ensureSuccess(),
+		ProcessFailedException::class,
+		'Process failed with non-zero exit code: 1',
+	);
+});
+
+test('ensureSuccess() does not throw on success', function () {
+	$process = Process::runExecutable(PHP_BINARY, ['-r', 'echo "ok";']);
+	$process->ensureSuccess();
+	Assert::same('ok', $process->getStdOutput());
+});
+
+test('run command with error', function () {
+	$process = Process::runCommand('"' . PHP_BINARY . '" -r "exit(1);"');
+	Assert::false($process->isSuccess());
+	Assert::same(1, $process->getExitCode());
+});
+
+test('run command ensure success throws exception on error', function () {
+	Assert::exception(
+		fn() => Process::runCommand('"' . PHP_BINARY . '" -r "exit(1);"')->ensureSuccess(),
+		ProcessFailedException::class,
+		'Process failed with non-zero exit code: 1',
+	);
+});
+
+
+// Process state monitoring
+
+test('is running', function () {
+	$process = Process::runExecutable(PHP_BINARY, ['-r', 'sleep(1);']);
+	Assert::true($process->isRunning());
+	$process->wait();
+	Assert::false($process->isRunning());
+});
+
+test('get pid', function () {
+	$process = Process::runExecutable(PHP_BINARY, ['-r', 'sleep(1);']);
+	Assert::type('int', $process->getPid());
+	$process->wait();
+	Assert::null($process->getPid());
+});
+
+
+// Waiting for process
+
+test('wait', function () {
+	$process = Process::runExecutable(PHP_BINARY, ['-r', 'echo "hello";']);
+	$process->wait();
+	$process->wait();
+	Assert::false($process->isRunning());
+	Assert::same(0, $process->getExitCode());
+	Assert::same('hello', $process->getStdOutput());
+});
+
+test('wait with callback', function () {
+	$output = '';
+	$error = '';
+	$process = Process::runExecutable(PHP_BINARY, ['-r', 'echo "hello"; fwrite(STDERR, "error");']);
+	$process->wait(function ($stdOut, $stdErr) use (&$output, &$error) {
+		$output .= $stdOut;
+		$error .= $stdErr;
+	});
+	Assert::same('hello', $output);
+	Assert::same('error', $error);
+});
+
+
+// Automatically call wait()
+
+test('getStdOutput() automatically call wait()', function () {
+	$process = Process::runExecutable(PHP_BINARY, ['-r', 'echo "hello";']);
+	Assert::same('hello', $process->getStdOutput());
+	Assert::false($process->isRunning());
+});
+
+test('getExitCode() automatically call wait()', function () {
+	$process = Process::runExecutable(PHP_BINARY, ['-r', 'exit(2);']);
+	Assert::same(2, $process->getExitCode());
+	Assert::false($process->isRunning());
+});
+
+test('reads large output without deadlocking', function () {
+	$process = Process::runExecutable(PHP_BINARY, ['-r', 'echo str_repeat("a", 1_000_000);']);
+	Assert::same(1_000_000, strlen($process->getStdOutput()));
+});
+
+
+// Terminating process
+
+test('terminate', function () {
+	$process = Process::runExecutable(PHP_BINARY, ['-r', 'sleep(5);']);
+	$process->terminate();
+	Assert::false($process->isRunning());
+});
+
+test('terminate() and then wait()', function () {
+	$process = Process::runExecutable(PHP_BINARY, ['-r', 'sleep(5);']);
+	$process->terminate();
+	$process->wait();
+	Assert::false($process->isRunning());
+});
+
+test('getExitCode() after terminate()', function () {
+	$process = Process::runExecutable(PHP_BINARY, ['-r', 'sleep(5);']);
+	$process->terminate();
+	Assert::type('int', $process->getExitCode());
+	Assert::false($process->isSuccess());
+});
+
+test('terminate() does not hang on a process that ignores SIGTERM', function () {
+	if (!function_exists('pcntl_signal')) {
+		Tester\Environment::skip('Requires the pcntl extension.');
+	}
+	$process = Process::runExecutable(PHP_BINARY, ['-r', 'pcntl_async_signals(true); pcntl_signal(SIGTERM, fn() => null); while (true) sleep(1);']);
+	usleep(100_000); // let the child install the handler
+	$process->terminate(); // would hang in proc_close() if only SIGTERM were sent
+	Assert::false($process->isRunning());
+});
+
+
+// Timeout
+
+test('timeout', function () {
+	Assert::exception(
+		fn() => Process::runExecutable(PHP_BINARY, ['-r', 'sleep(5);'], timeout: 0.1)->wait(),
+		ProcessTimeoutException::class,
+		'Process exceeded the time limit of 0.1 seconds',
+	);
+});
+
+
+// bypass_shell
+
+if (Helpers::IsWindows) {
+	test('bypass_shell = false', function () {
+		$process = Process::runCommand('"' . PHP_BINARY . '" -r "echo 123;"', options: ['bypass_shell' => false]);
+		Assert::same('123', $process->getStdOutput());
+	});
+}

tests/Utils/Process.basic.phpt

@@ -0,0 +1,52 @@
+<?php declare(strict_types=1);
+
+use Nette\Utils\Process;
+use Tester\Assert;
+
+require __DIR__ . '/../bootstrap.php';
+
+
+/**
+ * Reads the output incrementally: polls while the process runs, then reads the final chunk.
+ * The fixture flushes one byte every 50 ms and we poll every 20 ms, so the data reliably
+ * arrives in several chunks rather than all at once.
+ * @return string[]  the non-empty chunks in the order they were received
+ */
+$drain = function (Process $process, callable $consume): array {
+	$chunks = [];
+	do {
+		usleep(20_000);
+		if (($chunk = $consume($process)) !== '') {
+			$chunks[] = $chunk;
+		}
+	} while ($process->isRunning());
+
+	if (($chunk = $consume($process)) !== '') { // the part produced after the process finished
+		$chunks[] = $chunk;
+	}
+	return $chunks;
+};
+
+
+test('incremental output consumption', function () use ($drain) {
+	$process = Process::runExecutable(PHP_BINARY, ['-f', __DIR__ . '/fixtures.process/incremental.php', 'stdout']);
+	$chunks = $drain($process, fn(Process $p) => $p->consumeStdOutput());
+
+	Assert::same('helloworld', implode($chunks));
+	Assert::true(count($chunks) > 1, 'output should arrive in several chunks');
+	Assert::same('', $process->consumeStdOutput());
+	Assert::same('helloworld', $process->getStdOutput());
+});
+
+test('incremental error output consumption', function () use ($drain) {
+	$process = Process::runExecutable(PHP_BINARY, ['-f', __DIR__ . '/fixtures.process/incremental.php', 'stderr']);
+	$chunks = $drain($process, fn(Process $p) => $p->consumeStdError());
+
+	Assert::same('hello' . PHP_EOL . 'world' . PHP_EOL, implode($chunks));
+	Assert::true(count($chunks) > 1, 'error output should arrive in several chunks');
+	Assert::same('', $process->consumeStdError());
+	Assert::same('hello' . PHP_EOL . 'world' . PHP_EOL, $process->getStdError());
+});
+
+
+// TODO: Process::run() and Process::ensure() convenience methods

tests/Utils/Process.consume.phpt

@@ -0,0 +1,24 @@
+<?php declare(strict_types=1);
+
+use Nette\Utils\Process;
+use Tester\Assert;
+
+require __DIR__ . '/../bootstrap.php';
+
+
+// Environment variables
+
+test('environment variables', function () {
+	$process = Process::runExecutable(PHP_BINARY, ['-r', 'echo getenv("TEST_VAR");'], env: ['TEST_VAR' => '123']);
+	Assert::same('123', $process->getStdOutput());
+});
+
+test('no environment variables', function () {
+	$process = Process::runExecutable(PHP_BINARY, ['-r', 'echo !getenv("PATH") ? "ok" : "no";'], env: []);
+	Assert::same('ok', $process->getStdOutput());
+});
+
+test('parent environment variables', function () {
+	$process = Process::runExecutable(PHP_BINARY, ['-r', 'echo getenv("PATH") ? "ok" : "no";']);
+	Assert::same('ok', $process->getStdOutput());
+});

tests/Utils/Process.environment.phpt

@@ -0,0 +1,68 @@
+<?php declare(strict_types=1);
+
+use Nette\Utils\Process;
+use Tester\Assert;
+
+require __DIR__ . '/../bootstrap.php';
+
+
+// Different input types
+
+test('string as input', function () {
+	$input = 'Hello Input';
+	$process = Process::runExecutable(PHP_BINARY, ['-r', 'echo fgets(STDIN);'], stdin: $input);
+	Assert::same('Hello Input', $process->getStdOutput());
+});
+
+test('stream as input', function () {
+	$input = fopen('php://memory', 'r+');
+	fwrite($input, 'Hello Input');
+	rewind($input);
+	$process = Process::runExecutable(PHP_BINARY, ['-r', 'echo fgets(STDIN);'], stdin: $input);
+	Assert::same('Hello Input', $process->getStdOutput());
+});
+
+test('large string input', function () {
+	$input = str_repeat('x', 200_000); // larger than a typical OS pipe buffer
+	$process = Process::runExecutable(PHP_BINARY, ['-r', 'echo strlen(stream_get_contents(STDIN));'], stdin: $input);
+	Assert::same('200000', $process->getStdOutput());
+});
+
+test('invalid input type is rejected before the process starts', function () {
+	Assert::exception(
+		fn() => Process::runExecutable(PHP_BINARY, ['-r', 'sleep(10);'], stdin: false),
+		Nette\InvalidArgumentException::class,
+		'Input must be string, resource, Process or null, bool given.',
+	);
+});
+
+
+// Writing input
+
+test('write input', function () {
+	$process = Process::runExecutable(PHP_BINARY, ['-r', 'echo fgets(STDIN);'], stdin: null);
+	$process->writeStdInput('hello' . PHP_EOL);
+	$process->writeStdInput('world' . PHP_EOL);
+	$process->closeStdInput();
+	Assert::same('hello' . PHP_EOL, $process->getStdOutput());
+});
+
+test('writeStdInput() after closeStdInput() throws exception', function () {
+	$process = Process::runExecutable(PHP_BINARY, ['-r', 'echo fgets(STDIN);'], stdin: null);
+	$process->writeStdInput('hello' . PHP_EOL);
+	$process->closeStdInput();
+	Assert::exception(
+		fn() => $process->writeStdInput('world' . PHP_EOL),
+		Nette\InvalidStateException::class,
+		'Cannot write to process: STDIN pipe is closed',
+	);
+});
+
+test('writeStdInput() throws exception when stdin is not null', function () {
+	$process = Process::runExecutable(PHP_BINARY, ['-r', 'echo fgets(STDIN);']);
+	Assert::exception(
+		fn() => $process->writeStdInput('hello' . PHP_EOL),
+		Nette\InvalidStateException::class,
+		'Cannot write to process: STDIN pipe is closed',
+	);
+});