Do not launch command line in a shell (cmd.exe) by default on Windows

Author: clue

README.md

@@ -112,14 +112,30 @@ For more details, see the
 The `Process` class allows you to pass any kind of command line string:
 
 ```php
-$process = new Process('echo test');
+$process = new Process('echo test', …);
+$process->start($loop);
+```
+
+The command line string usually consists of a whitespace-separated list with
+your main executable bin and any number of arguments. Special care should be
+taken to quote any arguments via `escapeshellarg()` if you pass any user input
+along. Likewise, keep in mind that especially on Windows, it is rather common to
+have path names containing spaces and other special characters. If you want to
+run a binary like this, you will have to ensure this is quoted as a single
+argument like this:
+
+```php
+$bin = 'C:\\Program files (x86)\\PHP\\php.exe';
+$file = 'C:\\Users\\me\\Desktop\\Application\\main.php';
+
+$process = new Process(escapeshellarg($bin) . ' ' . escapeshellarg($file), …);
 $process->start($loop);
 ```
 
 By default, PHP will launch processes by wrapping the given command line string
-in a `sh` command on Unix, so that the above example will actually execute
-`sh -c echo test` under the hood on Unix. On Windows, it will launch processes
-by wrapping it in a `cmd` shell like `cmd /C echo test`.
+in a `sh` command on Unix, so that the first example will actually execute
+`sh -c echo test` under the hood on Unix. On Windows, it will not launch
+processes by wrapping them in a shell.
 
 This is a very useful feature because it does not only allow you to pass single
 commands, but actually allows you to pass any kind of shell command line and
@@ -133,6 +149,12 @@ $process = new Process('echo run && demo || echo failed');
 $process->start($loop);
 ```
 
+> Note that [Windows support](#windows-compatibility) is limited in that it
+  doesn't support STDIO streams at all and also that processes will not be run
+  in a wrapping shell by default. If you want to run a shell built-in function
+  such as `echo hello` or `sleep 10`, you may have to prefix your command line
+  with an explicit shell like `cmd /c echo hello`.
+
 In other words, the underlying shell is responsible for managing this command
 line and launching the individual sub-commands and connecting their STDIO
 streams as appropriate.
@@ -145,7 +167,7 @@ implement some higher-level protocol logic, such as printing an explicit
 boundary between each sub-command like this:
 
 ```php
-$process = new Process('cat first && echo --- && cat second');
+$process = new Process('cat first && echo --- && cat second', …);
 $process->start($loop);
 ```
 
@@ -154,7 +176,7 @@ its `exit` event to conditionally start the next process in the chain.
 This will give you an opportunity to configure the subsequent process I/O streams:
 
 ```php
-$first = new Process('cat first');
+$first = new Process('cat first', …);
 $first->start($loop);
 
 $first->on('exit', function () use ($loop) {
@@ -163,7 +185,7 @@ $first->on('exit', function () use ($loop) {
 });
 ```
 
-Keep in mind that PHP uses the shell wrapper for ALL command lines.
+Keep in mind that PHP uses the shell wrapper for ALL command lines on Unix.
 While this may seem reasonable for more complex command lines, this actually
 also applies to running the most simple single command:
 
@@ -172,7 +194,7 @@ $process = new Process('yes');
 $process->start($loop);
 ```
 
-This will actually spawn a command hierarchy similar to this:
+This will actually spawn a command hierarchy similar to this on Unix:
 
 ```
 5480 … \_ php example.php
@@ -525,6 +547,18 @@ want to run a child process on Windows, each with its own set of pros and cons:
     In this case, we suggest looking at the excellent
     [createprocess-windows](https://github.com/cubiclesoft/createprocess-windows).
 
+Additionally, note that the [command](#command) given to the `Process` will be
+passed to the underlying Windows-API
+([`CreateProcess`](https://docs.microsoft.com/en-us/windows/desktop/api/processthreadsapi/nf-processthreadsapi-createprocessa))
+as-is and the process will not be launched in a wrapping shell by default. In
+particular, this means that shell built-in functions such as `echo hello` or
+`sleep 10` may have to be prefixed with an explicit shell command like this:
+
+```php
+$process = new Process('cmd /c echo hello', null, null, $pipes);
+$process->start($loop);
+```
+
 ## Install
 
 The recommended way to install this library is [through Composer](https://getcomposer.org).

src/Process.php

@@ -145,7 +145,15 @@ public function start(LoopInterface $loop, $interval = 0.1)
             $cmd = sprintf('(%s) ' . $sigchild . '>/dev/null; code=$?; echo $code >&' . $sigchild . '; exit $code', $cmd);
         }
 
-        $this->process = proc_open($cmd, $fdSpec, $pipes, $this->cwd, $this->env);
+        // on Windows, we do not launch the given command line in a shell (cmd.exe) by default and omit any error dialogs
+        // the cmd.exe shell can explicitly be given as part of the command as detailed in both documentation and tests
+        $options = array();
+        if (DIRECTORY_SEPARATOR === '\\') {
+            $options['bypass_shell'] = true;
+            $options['suppress_errors'] = true;
+        }
+
+        $this->process = proc_open($cmd, $fdSpec, $pipes, $this->cwd, $this->env, $options);
 
         if (!is_resource($this->process)) {
             throw new \RuntimeException('Unable to launch a new process.');

tests/AbstractProcessTest.php

@@ -51,7 +51,11 @@ public function testStartWillAssignPipes()
 
     public function testStartWithoutAnyPipesWillNotAssignPipes()
     {
-        $process = new Process('exit 0', null, null, array());
+        if (DIRECTORY_SEPARATOR === '\\') {
+            $process = new Process('cmd /c exit 0', null, null, array());
+        } else {
+            $process = new Process('exit 0', null, null, array());
+        }
         $process->start($this->createLoop());
 
         $this->assertNull($process->stdin);
@@ -84,7 +88,7 @@ public function testIsRunning()
     {
         if (DIRECTORY_SEPARATOR === '\\') {
             // Windows doesn't have a sleep command and also does not support process pipes
-            $process = new Process('php -r ' . escapeshellarg('sleep(1);'), null, null, array());
+            $process = new Process($this->getPhpBinary() . ' -r ' . escapeshellarg('sleep(1);'), null, null, array());
         } else {
             $process = new Process('sleep 1');
         }
@@ -156,7 +160,11 @@ public function testReceivesProcessOutputFromStdoutRedirectedToFile()
     {
         $tmp = tmpfile();
 
-        $cmd = 'echo test';
+        if (DIRECTORY_SEPARATOR === '\\') {
+            $cmd = 'cmd /c echo test';
+        } else {
+            $cmd = 'echo test';
+        }
 
         $loop = $this->createLoop();
         $process = new Process($cmd, null, null, array(1 => $tmp));
@@ -168,6 +176,27 @@ public function testReceivesProcessOutputFromStdoutRedirectedToFile()
         $this->assertEquals('test', rtrim(stream_get_contents($tmp)));
     }
 
+    public function testReceivesProcessOutputFromTwoCommandsChainedStdoutRedirectedToFile()
+    {
+        $tmp = tmpfile();
+
+        if (DIRECTORY_SEPARATOR === '\\') {
+            // omit whitespace before "&&" and quotation marks as Windows will actually echo this otherwise
+            $cmd = 'cmd /c echo hello&& cmd /c echo world';
+        } else {
+            $cmd = 'echo "hello" && echo "world"';
+        }
+
+        $loop = $this->createLoop();
+        $process = new Process($cmd, null, null, array(1 => $tmp));
+        $process->start($loop);
+
+        $loop->run();
+
+        rewind($tmp);
+        $this->assertEquals("hello\nworld", str_replace("\r\n", "\n", rtrim(stream_get_contents($tmp))));
+    }
+
     public function testReceivesProcessOutputFromStdoutAttachedToSocket()
     {
         if (DIRECTORY_SEPARATOR === '\\') {
@@ -199,9 +228,14 @@ public function testReceivesProcessOutputFromStdoutRedirectedToSocketProcess()
         // create TCP/IP server on random port and wait for client connection
         $server = stream_socket_server('tcp://127.0.0.1:0');
 
-        $cmd = 'echo test';
+        if (DIRECTORY_SEPARATOR === '\\') {
+            $cmd = 'cmd /c echo test';
+        } else {
+            $cmd = 'exec echo test';
+        }
+
         $code = '$s=stream_socket_client($argv[1]);do{$d=fread(STDIN,8192);fwrite($s,$d);}while(!feof(STDIN));fclose($s);';
-        $cmd .= ' | php -r ' . escapeshellarg($code) . ' ' . escapeshellarg(stream_socket_get_name($server, false));
+        $cmd .= ' | ' . $this->getPhpBinary() . ' -r ' . escapeshellarg($code) . ' ' . escapeshellarg(stream_socket_get_name($server, false));
 
         $loop = $this->createLoop();
 
@@ -505,7 +539,13 @@ public function testDetectsClosingProcessEvenWhenAllStdioPipesHaveBeenClosed()
     public function testDetectsClosingProcessEvenWhenStartedWithoutPipes()
     {
         $loop = $this->createLoop();
-        $process = new Process('exit 0', null, null, array());
+
+        if (DIRECTORY_SEPARATOR === '\\') {
+            $process = new Process('cmd /c exit 0', null, null, array());
+        } else {
+            $process = new Process('exit 0', null, null, array());
+        }
+
         $process->start($loop, 0.001);
 
         $time = microtime(true);
@@ -548,10 +588,11 @@ public function testStartAlreadyRunningProcess()
     {
         if (DIRECTORY_SEPARATOR === '\\') {
             // Windows doesn't have a sleep command and also does not support process pipes
-            $process = new Process('php -r ' . escapeshellarg('sleep(1);'), null, null, array());
+            $process = new Process($this->getPhpBinary() . ' -r ' . escapeshellarg('sleep(1);'), null, null, array());
         } else {
             $process = new Process('sleep 1');
         }
+        //var_dump($process);
 
         $process->start($this->createLoop());
         $process->start($this->createLoop());
@@ -561,7 +602,7 @@ public function testTerminateProcesWithoutStartingReturnsFalse()
     {
         if (DIRECTORY_SEPARATOR === '\\') {
             // Windows doesn't have a sleep command and also does not support process pipes
-            $process = new Process('php -r ' . escapeshellarg('sleep(1);'), null, null, array());
+            $process = new Process($this->getPhpBinary() . ' -r ' . escapeshellarg('sleep(1);'), null, null, array());
         } else {
             $process = new Process('sleep 1');
         }
@@ -573,7 +614,7 @@ public function testTerminateWillExit()
     {
         if (DIRECTORY_SEPARATOR === '\\') {
             // Windows doesn't have a sleep command and also does not support process pipes
-            $process = new Process('php -r ' . escapeshellarg('sleep(10);'), null, null, array());
+            $process = new Process($this->getPhpBinary() . ' -r ' . escapeshellarg('sleep(10);'), null, null, array());
         } else {
             $process = new Process('sleep 10');
         }
@@ -771,6 +812,11 @@ public function assertSoon(\Closure $callback, $timeout = 20000, $interval = 200
         }
     }
 
+    /**
+     * Returns the path to the PHP binary. This is already escapescaped via `escapeshellarg()`.
+     *
+     * @return string
+     */
     private function getPhpBinary()
     {
         $runtime = new Runtime();