[Components][Process] mustRun() documentation

xabbuh · weaverryan · commit ad6a340e8e8e · 2014-10-01T10:20:52.000-04:00
diff --git a/components/process.rst b/components/process.rst
@@ -31,7 +31,7 @@ a command in a sub-process::
         throw new \RuntimeException($process->getErrorOutput());
     }
 
-    print $process->getOutput();
+    echo $process->getOutput();
 
 The component takes care of the subtle differences between the different platforms
 when executing the command.
@@ -50,6 +50,27 @@ the contents of the output and
 :method:`Symfony\\Component\\Process\\Process::clearErrorOutput` clears
 the contents of the error output.
 
+.. versionadded:: 2.5
+    The ``mustRun()`` method was introduced in Symfony 2.5.
+
+The ``mustRun()`` method is identical to ``run()``, except that it will throw
+a :class:`Symfony\\Component\\Process\\Exception\\ProcessFailedException`
+if the process couldn't be executed successfully (i.e. the process exited
+with a non-zero code)::
+
+    use Symfony\Component\Process\Exception\ProcessFailedException;
+    use Symfony\Component\Process\Process;
+
+    $process = new Process('ls -lsa');
+
+    try {
+        $process->mustRun();
+
+        echo $process->getOutput();
+    } catch (ProcessFailedException $e) {
+        echo $e->getMessage();
+    }
+
 Getting real-time Process Output
 --------------------------------
 
@@ -218,17 +239,17 @@ Process Idle Timeout
 .. versionadded:: 2.4
    The :method:`Symfony\\Component\\Process\\Process::setIdleTimeout` method
    was introduced in Symfony 2.4.
-   
+
 In contrast to the timeout of the previous paragraph, the idle timeout only
 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->setTimeout(3600);
    $process->setIdleTimeout(60);
    $process->run();
-   
+
 In the case above, a process is considered timed out, when either the total runtime
 exceeds 3600 seconds, or the process does not produce any output for 60 seconds.
 
