Merge branch '5.0'

javiereguiluz · javiereguiluz · commit d838ba6ad632 · 2019-12-20T17:28:43.000+01:00
* 5.0:
  Update paragraph about portable command lines
diff --git a/components/process.rst b/components/process.rst
@@ -107,7 +107,7 @@ Using Features From the OS Shell
 
 Using array of arguments is the recommended way to define commands. This
 saves you from any escaping and allows sending signals seamlessly
-(e.g. to stop processes before completion)::
+(e.g. to stop processes while they run)::
 
     $process = new Process(['/path/command', '--option', 'argument', 'etc.']);
     $process = new Process(['/path/to/php', '--define', 'memory_limit=1024M', '/path/to/script.php']);
@@ -134,6 +134,17 @@ environment variables using the second argument of the ``run()``,
     // On both Unix-like and Windows
     $process->run(null, ['MESSAGE' => 'Something to output']);
 
+If you prefer to create portable commands that are independent from the
+operating system, you can write the above command as follows::
+
+    // works the same on Windows , Linux and macOS
+    $process = Process::fromShellCommandline('echo "${:MESSAGE}"');
+
+Portable commands require using a syntax that is specific to the component: when
+enclosing a variable name into ``"{$:`` and ``}"`` exactly, the process object
+will replace it with its escaped value, or will fail if the variable is not
+found in the list of environment variables attached to the command.
+
 Setting Environment Variables for Processes
 -------------------------------------------
 
