Merge branch '4.1'

* 4.1:
  Fixing bad syntax
  Fixed grammar issue in console.rst
  Specify version for symfony/skeleton
  [Process] document command-as-arrays

Author: weaverryan

components/process.rst

@@ -30,7 +30,7 @@ escaping arguments to prevent security issues. It replaces PHP functions like
     use Symfony\Component\Process\Process;
     use Symfony\Component\Process\Exception\ProcessFailedException;
 
-    $process = new Process('ls -lsa');
+    $process = new Process(array('ls', '-lsa'));
     $process->run();
 
     // executes after the command finishes
@@ -68,7 +68,7 @@ You can also use the :class:`Symfony\\Component\\Process\\Process` class with th
 foreach construct to get the output while it is generated. By default, the loop waits
 for new output before going to the next iteration::
 
-    $process = new Process('ls -lsa');
+    $process = new Process(array('ls', '-lsa'));
     $process->start();
 
     foreach ($process as $type => $data) {
@@ -85,7 +85,7 @@ for new output before going to the next iteration::
     it is generated. That iterator is exposed via the ``getIterator()`` method
     to allow customizing its behavior::
 
-        $process = new Process('ls -lsa');
+        $process = new Process(array('ls', '-lsa'));
         $process->start();
         $iterator = $process->getIterator($process::ITER_SKIP_ERR | $process::ITER_KEEP_OUTPUT);
         foreach ($iterator as $data) {
@@ -100,7 +100,7 @@ with a non-zero code)::
     use Symfony\Component\Process\Exception\ProcessFailedException;
     use Symfony\Component\Process\Process;
 
-    $process = new Process('ls -lsa');
+    $process = new Process(array('ls', '-lsa'));
 
     try {
         $process->mustRun();
@@ -110,6 +110,38 @@ with a non-zero code)::
         echo $exception->getMessage();
     }
 
+.. tip::
+
+    .. versionadded:: 3.3
+        The ability to define commands as arrays of arguments was introduced in
+        Symfony 3.3.
+
+    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.)::
+
+        $process = new Process(array('/path/command', '--flag', 'arg 1', 'etc.'));
+
+    If you need use stream redirections, conditional execution, or any other
+    features provided by the shell of your operating system, you can also define
+    commands as strings.
+
+    Please note that each OS provides a different syntax for their command-lines
+    so that it becomes your responsibility to deal with escaping and portability.
+
+    To provide any variable arguments to command-line string, pass them as
+    environment variables using the second argument of the ``run()``,
+    ``mustRun()`` or ``start()`` methods. Referencing them is also OS-dependent::
+
+        // On Unix-like OSes (Linux, macOS)
+        $process = new Process('echo "$MESSAGE"');
+
+        // On Windows
+        $process = new Process('echo "!MESSAGE!"');
+
+        // On both Unix-like and Windows
+        $process->run(null, array('MESSAGE' => 'Something to output'));
+
 Getting real-time Process Output
 --------------------------------
 
@@ -120,7 +152,7 @@ anonymous function to the
 
     use Symfony\Component\Process\Process;
 
-    $process = new Process('ls -lsa');
+    $process = new Process(array('ls', '-lsa'));
     $process->run(function ($type, $buffer) {
         if (Process::ERR === $type) {
             echo 'ERR > '.$buffer;
@@ -139,7 +171,7 @@ process, the :method:`Symfony\\Component\\Process\\Process::isRunning` method
 to check if the process is done and the
 :method:`Symfony\\Component\\Process\\Process::getOutput` method to get the output::
 
-    $process = new Process('ls -lsa');
+    $process = new Process(array('ls', '-lsa'));
     $process->start();
 
     while ($process->isRunning()) {
@@ -151,7 +183,7 @@ to check if the process is done and the
 You can also wait for a process to end if you started it asynchronously and
 are done doing other stuff::
 
-    $process = new Process('ls -lsa');
+    $process = new Process(array('ls', '-lsa'));
     $process->start();
 
     // ... do other things
@@ -190,7 +222,7 @@ are done doing other stuff::
 a callback that is called repeatedly whilst the process is still running, passing
 in the output and its type::
 
-    $process = new Process('ls -lsa');
+    $process = new Process(array('ls', '-lsa'));
     $process->start();
 
     $process->wait(function ($type, $buffer) {
@@ -209,7 +241,7 @@ Before a process is started, you can specify its standard input using either the
 of the constructor. The provided input can be a string, a stream resource or a
 Traversable object::
 
-    $process = new Process('cat');
+    $process = new Process('cat']);
     $process->setInput('foobar');
     $process->run();
 
@@ -222,7 +254,7 @@ provides the :class:`Symfony\\Component\\Process\\InputStream` class::
     $input = new InputStream();
     $input->write('foo');
 
-    $process = new Process('cat');
+    $process = new Process(array('cat'));
     $process->setInput($input);
     $process->start();
 
@@ -248,7 +280,7 @@ The input of a process can also be defined using `PHP streams`_::
 
     $stream = fopen('php://temporary', 'w+');
 
-    $process = new Process('cat');
+    $process = new Process(array('cat'));
     $process->setInput($stream);
     $process->start();
 
@@ -274,7 +306,7 @@ is sent to the running process. The default signal sent to a process is ``SIGKIL
 Please read the :ref:`signal documentation below<reference-process-signal>`
 to find out more about signal handling in the Process component::
 
-    $process = new Process('ls -lsa');
+    $process = new Process(array('ls', '-lsa'));
     $process->start();
 
     // ... do other things
@@ -303,7 +335,7 @@ timeout (in seconds)::
 
     use Symfony\Component\Process\Process;
 
-    $process = new Process('ls -lsa');
+    $process = new Process(array('ls', '-lsa'));
     $process->setTimeout(3600);
     $process->run();
 
@@ -335,7 +367,7 @@ considers the time since the last output was produced by the process::
 
     use Symfony\Component\Process\Process;
 
-    $process = new Process('something-with-variable-runtime');
+    $process = new Process(array('something-with-variable-runtime'));
     $process->setTimeout(3600);
     $process->setIdleTimeout(60);
     $process->run();
@@ -351,21 +383,12 @@ When running a program asynchronously, you can send it POSIX signals with the
 
     use Symfony\Component\Process\Process;
 
-    $process = new Process('find / -name "rabbit"');
+    $process = new Process(array('find', '/', '-name', 'rabbit'));
     $process->start();
 
     // will send a SIGKILL to the process
     $process->signal(SIGKILL);
 
-.. caution::
-
-    Due to some limitations in PHP, if you're using signals with the Process
-    component, you may have to prefix your commands with `exec`_. Please read
-    `Symfony Issue#5759`_ and `PHP Bug#39992`_ to understand why this is happening.
-
-    POSIX signals are not available on Windows platforms, please refer to the
-    `PHP documentation`_ for available signals.
-
 Process Pid
 -----------
 
@@ -374,17 +397,11 @@ You can access the `pid`_ of a running process with the
 
     use Symfony\Component\Process\Process;
 
-    $process = new Process('/usr/bin/php worker.php');
+    $process = new Process(array('/usr/bin/php', 'worker.php'));
     $process->start();
 
     $pid = $process->getPid();
 
-.. caution::
-
-    Due to some limitations in PHP, if you want to get the pid of a symfony Process,
-    you may have to prefix your commands with `exec`_. Please read
-    `Symfony Issue#5759`_ to understand why this is happening.
-
 Disabling Output
 ----------------
 
@@ -395,7 +412,7 @@ Use :method:`Symfony\\Component\\Process\\Process::disableOutput` and
 
     use Symfony\Component\Process\Process;
 
-    $process = new Process('/usr/bin/php worker.php');
+    $process = new Process(array('/usr/bin/php', 'worker.php'));
     $process->disableOutput();
     $process->run();
 

console.rst

@@ -259,7 +259,7 @@ Now, you can pass the username to the command:
 Getting Services from the Service Container
 -------------------------------------------
 
-To actually create a new user, the command has to access to some
+To actually create a new user, the command has to access some
 :doc:`services </service_container>`. Since your command is already registered
 as a service, you can use normal dependency injection. Imagine you have a
 ``App\Service\UserManager`` service that you want to access::

frontend/encore/installation-no-flex.rst

@@ -1,7 +1,7 @@
 Encore Installation (without Symfony Flex)
 ==========================================
 
-.. tip:
+.. tip::
 
     If your project uses Symfony Flex, read :doc:`/frontend/encore/installation`
     for easier instructions.

frontend/encore/installation.rst

@@ -1,7 +1,7 @@
 Installing Encore (with Symfony Flex)
 =====================================
 
-.. tip:
+.. tip::
 
     If your project does **not** use Symfony Flex, read :doc:`/frontend/encore/installation-no-flex`.
 

setup/flex.rst

@@ -111,7 +111,7 @@ Symfony application by executing the following command:
 
 .. code-block:: terminal
 
-    $ composer create-project symfony/skeleton my-project
+    $ composer create-project symfony/skeleton:3.4.* my-project
 
 .. note::