8000 Merge branch '3.4' into 4.1 · symfony/symfony-docs@9d96dae · GitHub
[go: up one dir, main page]
Skip to content

Commit 9d96dae

Browse filesBrowse files
weaverryanweaverryan
committed
Merge branch '3.4' into 4.1
* 3.4: Fixing bad syntax Fixed grammar issue in console.rst Specify version for symfony/skeleton [Process] document command-as-arrays
2 parents 72ef190 + 5c2842e commit 9d96dae

File tree

5 files changed

+53
-36
lines changed

5 files changed

+53
-36
lines changed

‎components/process.rst

Lines changed: 49 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ escaping arguments to prevent security issues. It replaces PHP functions like
3030
use Symfony\Component\Process\Process;
3131
use Symfony\Component\Process\Exception\ProcessFailedException;
3232

33-
$process = new Process('ls -lsa');
33+
$process = new Process(array('ls', '-lsa'));
3434
$process->run();
3535

3636
// executes after the command finishes
@@ -68,7 +68,7 @@ You can also use the :class:`Symfony\\Component\\Process\\Process` class with th
6868
foreach construct to get the output while it is generated. By default, the loop waits
6969
for new output before going to the next iteration::
7070

71-
$process = new Process('ls -lsa');
71+
$process = new Process(array('ls', '-lsa'));
7272
$process->start();
7373

7474
foreach ($process as $type => $data) {
@@ -85,7 +85,7 @@ for new output before going to the next iteration::
8585
it is generated. That iterator is exposed via the ``getIterator()`` method
8686
to allow customizing its behavior::
8787

88-
$process = new Process('ls -lsa');
88+
$process = new Process(array('ls', '-lsa'));
8989
$process->start();
9090
$iterator = $process->getIterator($process::ITER_SKIP_ERR | $process::ITER_KEEP_OUTPUT);
9191
foreach ($iterator as $data) {
@@ -100,7 +100,7 @@ with a non-zero code)::
100100
use Symfony\Component\Process\Exception\ProcessFailedException;
101101
use Symfony\Component\Process\Process;
102102

103-
$process = new Process('ls -lsa');
103+
$process = new Process(array('ls', '-lsa'));
104104

105105
try {
106106
$process->mustRun();
@@ -110,6 +110,38 @@ with a non-zero code)::
110110
echo $exception->getMessage();
111111
}
112112

113+
.. tip::
114+
115+
.. versionadded:: 3.3
116+
The ability to define commands as arrays of arguments was introduced in
117+
Symfony 3.3.
118+
119+
Using array of arguments is the recommended way to define commands. This
120+
saves you from any escaping and allows sending signals seamlessly
121+
(e.g. to stop processes before completion.)::
122+
123+
$process = new Process(array('/path/command', '--flag', 'arg 1', 'etc.'));
124+
125+
If you need use stream redirections, conditional execution, or any other
126+
features provided by the shell of your operating system, you can also define
127+
commands as strings.
128+
129+
Please note that each OS provides a different syntax for their command-lines
130+
so that it becomes your responsibility to deal with escaping and portability.
131+
132+
To provide any variable arguments to command-line string, pass them as
133+
environment variables using the second argument of the ``run()``,
134+
``mustRun()`` or ``start()`` methods. Referencing them is also OS-dependent::
135+
136+
// On Unix-like OSes (Linux, macOS)
137+
$process = new Process('echo "$MESSAGE"');
138+
139+
// On Windows
140+
$process = new Process('echo "!MESSAGE!"');
141+
142+
// On both Unix-like and Windows
143+
$process->run(null, array('MESSAGE' => 'Something to output'));
144+
113145
Getting real-time Process Output
114146
--------------------------------
115147

@@ -120,7 +152,7 @@ anonymous function to the
120152

121153
use Symfony\Component\Process\Process;
122154

123-
$process = new Process('ls -lsa');
155+
$process = new Process(array('ls', '-lsa'));
124156
$process->run(function ($type, $buffer) {
125157
if (Process::ERR === $type) {
126158
echo 'ERR > '.$buffer;
@@ -139,7 +171,7 @@ process, the :method:`Symfony\\Component\\Process\\Process::isRunning` method
139171
to check if the process is done and the
140172
:method:`Symfony\\Component\\Process\\Process::getOutput` method to get the output::
141173

142-
$process = new Process('ls -lsa');
174+
$process = new Process(array('ls', '-lsa'));
143175
$process->start();
144176

145177
while ($process->isRunning()) {
@@ -151,7 +183,7 @@ to check if the process is done and the
151183
You can also wait for a process to end if you started it asynchronously and
152184
are done doing other stuff::
153185

154-
$process = new Process('ls -lsa');
186+
$process = new Process(array('ls', '-lsa'));
155187
$process->start();
156188

157189
// ... do other things
@@ -190,7 +222,7 @@ are done doing other stuff::
190222
a callback that is called repeatedly whilst the process is still running, passing
191223
in the output and its type::
192224

193-
$process = new Process('ls -lsa');
225+
$process = new Process(array('ls', '-lsa'));
194226
$process->start();
195227

196228
$process->wait(function ($type, $buffer) {
@@ -209,7 +241,7 @@ Before a process is started, you can specify its standard input using either the
209241
of the constructor. The provided input can be a string, a stream resource or a
210242
Traversable object::
211243

212-
$process = new Process('cat');
244+
$process = new Process('cat']);
213245
$process->setInput('foobar');
214246
$process->run();
215247

@@ -222,7 +254,7 @@ provides the :class:`Symfony\\Component\\Process\\InputStream` class::
222254
$input = new InputStream();
223255
$input->write('foo');
224256

225-
$process = new Process('cat');
257+
$process = new Process(array('cat'));
226258
$process->setInput($input);
227259
$process->start();
228260

@@ -248,7 +280,7 @@ The input of a process can also be defined using `PHP streams`_::
248280

249281
$stream = fopen('php://temporary', 'w+');
250282

251-
$process = new Process('cat');
283+
$process = new Process(array('cat'));
252284
$process->setInput($stream);
253285
$process->start();
254286

@@ -274,7 +306,7 @@ is sent to the running process. The default signal sent to a process is ``SIGKIL
274306
Please read the :ref:`signal documentation below<reference-process-signal>`
275307
to find out more about signal handling in the Process component::
276308

277-
$process = new Process('ls -lsa');
309+
$process = new Process(array('ls', '-lsa'));
278310
$process->start();
279311

280312
// ... do other things
@@ -303,7 +335,7 @@ timeout (in seconds)::
303335

304336
use Symfony\Component\Process\Process;
305337

306-
$process = new Process('ls -lsa');
338+
$process = new Process(array('ls', '-lsa'));
307339
$process->setTimeout(3600);
308340
$process->run();
309341

@@ -335,7 +367,7 @@ considers the time since the last output was produced by the process::
335367

336368
use Symfony\Component\Process\Process;
337369

338-
$process = new Process('something-with-variable-runtime');
370+
$process = new Process(array('something-with-variable-runtime'));
339371
$process->setTimeout(3600);
340372
$process->setIdleTimeout(60);
341373
$process->run();
@@ -351,21 +383,12 @@ When running a program asynchronously, you can send it POSIX signals with the
351383

352384
use Symfony\Component\Process\Process;
353385

354-
$process = new Process('find / -name "rabbit"');
386+
$process = new Process(array('find', '/', '-name', 'rabbit'));
355387
$process->start();
356388

357389
// will send a SIGKILL to the process
358390
$process->signal(SIGKILL);
359391

360-
.. caution::
361-
362-
Due to some limitations in PHP, if you're using signals with the Process
363-
component, you may have to prefix your commands with `exec`_. Please read
364-
`Symfony Issue#5759`_ and `PHP Bug#39992`_ to understand why this is happening.
365-
366-
POSIX signals are not available on Windows platforms, please refer to the
367-
`PHP documentation`_ for available signals.
368-
369392
Process Pid
370393
-----------
371394

@@ -374,17 +397,11 @@ You can access the `pid`_ of a running process with the
374397

375398
use Symfony\Component\Process\Process;
376399

377-
$process = new Process('/usr/bin/php worker.php');
400+
$process = new Process(array('/usr/bin/php', 'worker.php'));
378401
$process->start();
379402

380403
$pid = $process->getPid();
381404

382-
.. caution::
383-
384-
Due to some limitations in PHP, if you want to get the pid of a symfony Process,
385-
you may have to prefix your commands with `exec`_. Please read
386-
`Symfony Issue#5759`_ to understand why this is happening.
387-
388405
Disabling Output
389406
----------------
390407

@@ -395,7 +412,7 @@ Use :method:`Symfony\\Component\\Process\\Process::disableOutput` and
395412

396413
use Symfony\Component\Process\Process;
397414

398-
$process = new Process('/usr/bin/php worker.php');
415+
$process = new Process(array('/usr/bin/php', 'worker.php'));
399416
$process->disableOutput();
400417
$process->run();
401418

‎console.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -259,7 +259,7 @@ Now, you can pass the username to the command:
259259
Getting Services from the Service Container
260260
-------------------------------------------
261261

262-
To actually create a new user, the command has to access to some
262+
To actually create a new user, the command has to access some
263263
:doc:`services </service_container>`. Since your command is already registered
264264
as a service, you can use normal dependency injection. Imagine you have a
265265
``App\Service\UserManager`` service that you want to access::

‎frontend/encore/installation-no-flex.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
Encore Installation (without Symfony Flex)
22
==========================================
33

4-
.. tip:
4+
.. tip::
55

66
If your project uses Symfony Flex, read :doc:`/frontend/encore/installation`
77
for easier instructions.

‎frontend/encore/installation.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
Installing Encore (with Symfony Flex)
22
=====================================
33

4-
.. tip:
4+
.. tip::
55

66
If your project does **not** use Symfony Flex, read :doc:`/frontend/encore/installation-no-flex`.
77

‎setup/flex.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ Symfony application by executing the following command:
111111

112112
.. code-block:: terminal
113113
114-
$ composer create-project symfony/skeleton my-project
114+
$ composer create-project symfony/skeleton:3.4.* my-project
115115
116116
.. note::
117117

0 commit comments

Comments
 (0)
0