Skip to content

Commit 6b4794c

Browse files
weaverryanweaverryan
committed
Merge branch '2.2'
2 parents 647fd97 + f2b48c7 commit 6b4794c

39 files changed

+735
-216
lines changed

‎book/controller.rst

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -726,8 +726,12 @@ headers and content that's sent back to the client::
726726

727727
.. tip::
728728

729-
There is also a special :class:`Symfony\\Component\\HttpFoundation\\JsonResponse`
730-
class that helps return JSON responses. See :ref:`component-http-foundation-json-response`.
729+
There are also special classes to make certain kinds of responses easier:
730+
731+
- For JSON, there is :class:`Symfony\\Component\\HttpFoundation\\JsonResponse`.
732+
See :ref:`component-http-foundation-json-response`.
733+
- For files, there is :class:`Symfony\\Component\\HttpFoundation\\BinaryFileResponse`.
734+
See :ref:`component-http-foundation-serving-files`.
731735

732736
.. index::
733737
single: Controller; Request object

‎book/installation.rst

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -172,9 +172,13 @@ Symfony itself - into the ``vendor/`` directory.
172172
When running ``php composer.phar install`` or ``php composer.phar update``,
173173
composer will execute post install/update commands to clear the cache
174174
and install assets. By default, the assets will be copied into your ``web``
175-
directory. To create symlinks instead of copying the assets, you can
176-
add an entry in the ``extra`` node of your composer.json file with the
177-
key ``symfony-assets-install`` and the value ``symlink``:
175+
directory.
176+
177+
Instead of copying your Symfony assets, you can create symlinks if
178+
your operating system supports it. To create symlinks, add an entry
179+
in the ``extra`` node of your composer.json file with the key
180+
``symfony-assets-install`` and the value ``symlink``:
181+
178182

179183
.. code-block:: json
180184

‎book/propel.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ you:
6868

6969
In this example, you have one configured connection, named ``default``. If
7070
you want to configure more than one connection, read the `PropelBundle
71-
configuration section <Working With Symfony2 - Configuration>`_.
71+
configuration section`_.
7272

7373
Creating a Model Class
7474
~~~~~~~~~~~~~~~~~~~~~~
@@ -434,7 +434,7 @@ Commands
434434
You should read the dedicated section for `Propel commands in Symfony2`_.
435435

436436
.. _`Working With Symfony2`: http://propelorm.org/cookbook/symfony2/working-with-symfony2.html#installation
437-
.. _`Working With Symfony2 - Configuration`: http://propelorm.org/cookbook/symfony2/working-with-symfony2.html#configuration
437+
.. _`PropelBundle configuration section`: http://propelorm.org/cookbook/symfony2/working-with-symfony2.html#configuration
438438
.. _`Relationships`: http://propelorm.org/documentation/04-relationships.html
439439
.. _`Behaviors reference section`: http://propelorm.org/documentation/#behaviors_reference
440440
.. _`Propel commands in Symfony2`: http://propelorm.org/cookbook/symfony2/working-with-symfony2#the_commands

‎book/routing.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -681,7 +681,7 @@ be accomplished with the following route configuration:
681681
682682
return $collection;
683683
684-
.. versionadded::
684+
.. versionadded:: 2.2
685685
The ``methods`` option is added in Symfony2.2. Use the ``_method``
686686
requirement in older versions.
687687

‎book/templating.rst

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1344,8 +1344,13 @@ is being escaped for HTML output.
13441344
In some cases, you'll need to disable output escaping when you're rendering
13451345
a variable that is trusted and contains markup that should not be escaped.
13461346
Suppose that administrative users are able to write articles that contain
1347-
HTML code. By default, Twig will escape the article body. To render it normally,
1348-
add the ``raw`` filter: ``{{ article.body|raw }}``.
1347+
HTML code. By default, Twig will escape the article body.
1348+
1349+
To render it normally, add the ``raw`` filter:
1350+
1351+
.. code-block:: jinja
1352+
1353+
{{ article.body|raw }}
13491354
13501355
You can also disable output escaping inside a ``{% block %}`` area or
13511356
for an entire template. For more information, see `Output Escaping`_ in

‎book/testing.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -345,6 +345,16 @@ or perform more complex requests::
345345
// Directly submit a form (but using the Crawler is easier!)
346346
$client->request('POST', '/submit', array('name' => 'Fabien'));
347347

348+
// Submit a raw JSON string in the requst body
349+
$client->request(
350+
'POST',
351+
'/submit',
352+
array(),
353+
array(),
354+
array('CONTENT_TYPE' => 'application/json'),
355+
'{"name":"Fabien"}'
356+
);
357+
348358
// Form submission with a file upload
349359
use Symfony\Component\HttpFoundation\File\UploadedFile;
350360

‎components/console/introduction.rst

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,39 @@ You can also set these colors and options inside the tagname::
160160
// bold text on a yellow background
161161
$output->writeln('<bg=yellow;options=bold>foo</bg=yellow;options=bold>');
162162

163+
Verbosity Levels
164+
~~~~~~~~~~~~~~~~
165+
166+
The console has 3 levels of verbosity. These are defined in the
167+
:class:`Symfony\\Component\\Console\\Output\\OutputInterface`:
168+
169+
================================== ===============================
170+
Option Value
171+
================================== ===============================
172+
OutputInterface::VERBOSITY_QUIET Do not output any messages
173+
OutputInterface::VERBOSITY_NORMAL The default verbosity level
174+
OutputInterface::VERBOSITY_VERBOSE Increased verbosity of messages
175+
================================== ===============================
176+
177+
You can specify the quiet verbosity level with the ``--quiet`` or ``-q``
178+
option. The ``--verbose`` or ``-v`` option is used when you want an increased
179+
level of verbosity.
180+
181+
.. tip::
182+
183+
The full exception stacktrace is printed if the ``VERBOSITY_VERBOSE``
184+
level is used.
185+
186+
It is possible to print a message in a command for only a specific verbosity
187+
level. For example::
188+
189+
if (OutputInterface::VERBOSITY_VERBOSE === $output->getVerbosity()) {
190+
$output->writeln(...);
191+
}
192+
193+
When the quiet level is used, all output is suppressed as the default
194+
:method:`Symfony\Component\Console\Output::write<Symfony\\Component\\Console\\Output::write>`
195+
method returns without actually printing.
163196

164197
Using Command Arguments
165198
-----------------------

‎components/dependency_injection/compilation.rst

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -316,7 +316,10 @@ something needed in everyday use.
316316
The compiler pass must have the ``process`` method which is passed the container
317317
being compiled::
318318

319-
class CustomCompilerPass
319+
use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
320+
use Symfony\Component\DependencyInjection\ContainerBuilder;
321+
322+
class CustomCompilerPass implements CompilerPassInterface
320323
{
321324
public function process(ContainerBuilder $container)
322325
{

‎components/dom_crawler.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -278,16 +278,16 @@ To work with multi-dimensional fields::
278278
<input name="multi[dimensional]" />
279279
</form>
280280

281-
You must specify the fully qualified name of the field::
281+
Pass an array of values::
282282

283283
// Set a single field
284-
$form->setValue('multi[0]', 'value');
284+
$form->setValues(array('multi' => array('value')));
285285

286286
// Set multiple fields at once
287-
$form->setValue('multi', array(
287+
$form->setValues(array('multi' => array(
288288
1 => 'value',
289289
'dimensional' => 'an other value'
290-
));
290+
)));
291291

292292
This is great, but it gets better! The ``Form`` object allows you to interact
293293
with your form like a browser, selecting radio values, ticking checkboxes,

‎components/http_foundation/introduction.rst

Lines changed: 46 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -406,13 +406,25 @@ represented by a PHP callable instead of a string::
406406
});
407407
$response->send();
408408

409-
Downloading Files
410-
~~~~~~~~~~~~~~~~~
409+
.. note::
410+
411+
The ``flush()`` function does not flush buffering. If ``ob_start()`` has
412+
been called before or the ``output_buffering`` php.ini option is enabled,
413+
you must call ``ob_flush()`` before ``flush()``.
414+
415+
Additionally, PHP isn't the only layer that can buffer output. Your web
416+
server might also buffer based on its configuration. Even more, if you
417+
use fastcgi, buffering can't be disabled at all.
418+
419+
.. _component-http-foundation-serving-files:
420+
421+
Serving Files
422+
~~~~~~~~~~~~~
411423

412424
.. versionadded:: 2.1
413425
The ``makeDisposition`` method was added in Symfony 2.1.
414426

415-
When uploading a file, you must add a ``Content-Disposition`` header to your
427+
When sending a file, you must add a ``Content-Disposition`` header to your
416428
response. While creating this header for basic file downloads is easy, using
417429
non-ASCII filenames is more involving. The
418430
:method:`Symfony\\Component\\HttpFoundation\\Response::makeDisposition`
@@ -424,6 +436,33 @@ abstracts the hard work behind a simple API::
424436

425437
$response->headers->set('Content-Disposition', $d);
426438

439+
.. versionadded:: 2.2
440+
The :class:`Symfony\\Component\\HttpFoundation\\BinaryFileResponse`
441+
class was added in Symfony 2.2.
442+
443+
Alternatively, if you are serving a static file, you can use a
444+
:class:`Symfony\\Component\\HttpFoundation\\BinaryFileResponse`::
445+
446+
use Symfony\Component\HttpFoundation\BinaryFileResponse
447+
448+
$file = 'path/to/file.txt';
449+
$response = new BinaryFileResponse($file);
450+
451+
The ``BinaryFileResponse`` will automatically handle ``Range`` and
452+
``If-Range`` headers from the request. It also supports ``X-Sendfile``
453+
(see for `Nginx`_ and `Apache`_). To make use of it, you need to determine
454+
whether or not the ``X-Sendfile-Type`` header should be trusted and call
455+
:method:`Symfony\\Component\\HttpFoundation\\BinaryFileResponse::trustXSendfileTypeHeader`
456+
if it should::
457+
458+
$response::trustXSendfileTypeHeader();
459+
460+
You can still set the ``Content-Type`` of the sent file, or change its ``Content-Disposition``::
461+
462+
$response->headers->set('Content-Type', 'text/plain')
463+
$response->setContentDisposition(ResponseHeaderBag::DISPOSITION_ATTACHMENT, 'filename.txt');
464+
465+
427466
.. _component-http-foundation-json-response:
428467

429468
Creating a JSON Response
@@ -442,7 +481,8 @@ right content and headers. A JSON response might look like this::
442481
$response->headers->set('Content-Type', 'application/json');
443482

444483
.. versionadded:: 2.1
445-
The :class:`Symfony\\Component\\HttpFoundation\\JsonResponse` class was added in Symfony 2.1.
484+
The :class:`Symfony\\Component\\HttpFoundation\\JsonResponse`
485+
class was added in Symfony 2.1.
446486

447487
There is also a helpful :class:`Symfony\\Component\\HttpFoundation\\JsonResponse`
448488
class, which can make this even easier::
@@ -473,3 +513,5 @@ Session
473513
The session information is in its own document: :doc:`/components/http_foundation/sessions`.
474514

475515
.. _Packagist: https://packagist.org/packages/symfony/http-foundation
516+
.. _Nginx: http://wiki.nginx.org/XSendfile
517+
.. _Apache: https://tn123.org/mod_xsendfile/

‎components/map.rst.inc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727

2828
* :doc:`/components/dependency_injection/introduction`
2929
* :doc:`/components/dependency_injection/types`
30-
* :doc:`/components/dependency_injection/parameter`
30+
* :doc:`/components/dependency_injection/parameters`
3131
* :doc:`/components/dependency_injection/definitions`
3232
* :doc:`/components/dependency_injection/compilation`
3333
* :doc:`/components/dependency_injection/tags`

‎components/process.rst

Lines changed: 40 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -26,15 +26,16 @@ a command in a sub-process::
2626
$process = new Process('ls -lsa');
2727
$process->setTimeout(3600);
2828
$process->run();
29+
30+
// executes after the the command finishes
2931
if (!$process->isSuccessful()) {
3032
throw new \RuntimeException($process->getErrorOutput());
3133
}
3234

3335
print $process->getOutput();
3436

35-
The :method:`Symfony\\Component\\Process\\Process::run` method takes care
36-
of the subtle differences between the different platforms when executing the
37-
command.
37+
The component takes care of the subtle differences between the different platforms
38+
when executing the command.
3839

3940
.. versionadded:: 2.2
4041
The ``getIncrementalOutput()`` and ``getIncrementalErrorOutput()`` methods were added in Symfony 2.2.
@@ -60,6 +61,41 @@ anonymous function to the
6061
echo 'OUT > '.$buffer;
6162
}
6263
});
64+
65+
.. versionadded:: 2.1
66+
The non-blocking feature was added in 2.1.
67+
68+
You can also start the subprocess and then let it run asynchronously, retrieving
69+
output and the status in your main process whenever you need it. Use the
70+
:method:`Symfony\\Component\\Process\\Process::start` method to start an asynchronous
71+
process, the :method:`Symfony\\Component\\Process\\Process::isRunning` method
72+
to check if the process is done and the
73+
:method:`Symfony\\Component\\Process\\Process::getOutput` method to get the output::
74+
75+
$process = new Process('ls -lsa');
76+
$process->start();
77+
78+
while ($process->isRunning()) {
79+
// waiting for process to finish
80+
}
81+
82+
echo $process->getOutput();
83+
84+
You can also wait for a process to end if you started it asynchronously and
85+
are done doing other stuff::
86+
87+
$process = new Process('ls -lsa');
88+
$process->start();
89+
90+
// do other things
91+
92+
$process->wait(function ($type, $buffer) {
93+
if ('err' === $type) {
94+
echo 'ERR > '.$buffer;
95+
} else {
96+
echo 'OUT > '.$buffer;
97+
}
98+
});
6399

64100
If you want to execute some PHP code in isolation, use the ``PhpProcess``
65101
instead::
@@ -73,7 +109,7 @@ instead::
73109
$process->run();
74110

75111
.. versionadded:: 2.1
76-
The ``ProcessBuilder`` class has been as of 2.1.
112+
The ``ProcessBuilder`` class was added in Symfony 2.1.
77113

78114
To make your code work better on all platforms, you might want to use the
79115
:class:`Symfony\\Component\\Process\\ProcessBuilder` class instead::

‎components/serializer.rst

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,11 @@ use the Serializer service created before::
9393
$person->setName('foo');
9494
$person->setAge(99);
9595

96-
$serializer->serialize($person, 'json'); // Output: {"name":"foo","age":99}
96+
$jsonContent = $serializer->serialize($person, 'json');
97+
98+
// $jsonContent contains {"name":"foo","age":99}
99+
100+
echo $jsonContent; // or return it in a Response
97101

98102
The first parameter of the :method:`Symfony\\Component\\Serializer\\Serializer::serialize`
99103
is the object to be serialized and the second is used to choose the proper encoder,

‎cookbook/bundles/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ Bundles
44
.. toctree::
55
:maxdepth: 2
66

7+
installation
78
best_practices
89
inheritance
910
override

0 commit comments

Comments
 (0)