Merge branch '2.2'

Author: weaverryan

book/controller.rst

@@ -726,8 +726,12 @@ headers and content that's sent back to the client::
 
 .. tip::
 
-    There is also a special :class:`Symfony\\Component\\HttpFoundation\\JsonResponse`
-    class that helps return JSON responses. See :ref:`component-http-foundation-json-response`.
+    There are also special classes to make certain kinds of responses easier:
+
+    - For JSON, there is :class:`Symfony\\Component\\HttpFoundation\\JsonResponse`.
+      See :ref:`component-http-foundation-json-response`.
+    - For files, there is :class:`Symfony\\Component\\HttpFoundation\\BinaryFileResponse`.
+      See :ref:`component-http-foundation-serving-files`.
 
 .. index::
    single: Controller; Request object

book/installation.rst

@@ -172,9 +172,13 @@ Symfony itself - into the ``vendor/`` directory.
     When running ``php composer.phar install`` or ``php composer.phar update``,
     composer will execute post install/update commands to clear the cache
     and install assets. By default, the assets will be copied into your ``web``
-    directory. To create symlinks instead of copying the assets, you can
-    add an entry in the ``extra`` node of your composer.json file with the
-    key ``symfony-assets-install`` and the value ``symlink``:
+    directory. 
+
+    Instead of copying your Symfony assets, you can create symlinks if
+    your operating system supports it. To create symlinks, add an entry
+    in the ``extra`` node of your composer.json file with the key
+    ``symfony-assets-install`` and the value ``symlink``:
+
 
     .. code-block:: json
 

book/propel.rst

@@ -68,7 +68,7 @@ you:
 
     In this example, you have one configured connection, named ``default``. If
     you want to configure more than one connection, read the `PropelBundle
-    configuration section <Working With Symfony2 - Configuration>`_.
+    configuration section`_.
 
 Creating a Model Class
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -434,7 +434,7 @@ Commands
 You should read the dedicated section for `Propel commands in Symfony2`_.
 
 .. _`Working With Symfony2`: http://propelorm.org/cookbook/symfony2/working-with-symfony2.html#installation
-.. _`Working With Symfony2 - Configuration`: http://propelorm.org/cookbook/symfony2/working-with-symfony2.html#configuration
+.. _`PropelBundle configuration section`: http://propelorm.org/cookbook/symfony2/working-with-symfony2.html#configuration
 .. _`Relationships`: http://propelorm.org/documentation/04-relationships.html
 .. _`Behaviors reference section`: http://propelorm.org/documentation/#behaviors_reference
 .. _`Propel commands in Symfony2`: http://propelorm.org/cookbook/symfony2/working-with-symfony2#the_commands

book/routing.rst

@@ -681,7 +681,7 @@ be accomplished with the following route configuration:
 
         return $collection;
 
-.. versionadded::
+.. versionadded:: 2.2
     The ``methods`` option is added in Symfony2.2. Use the ``_method``
     requirement in older versions.
 

book/templating.rst

@@ -1344,8 +1344,13 @@ is being escaped for HTML output.
 In some cases, you'll need to disable output escaping when you're rendering
 a variable that is trusted and contains markup that should not be escaped.
 Suppose that administrative users are able to write articles that contain
-HTML code. By default, Twig will escape the article body. To render it normally,
-add the ``raw`` filter: ``{{ article.body|raw }}``.
+HTML code. By default, Twig will escape the article body.
+
+To render it normally, add the ``raw`` filter: 
+
+.. code-block:: jinja
+
+    {{ article.body|raw }}
 
 You can also disable output escaping inside a ``{% block %}`` area or
 for an entire template. For more information, see `Output Escaping`_ in

book/testing.rst

@@ -345,6 +345,16 @@ or perform more complex requests::
     // Directly submit a form (but using the Crawler is easier!)
     $client->request('POST', '/submit', array('name' => 'Fabien'));
 
+    // Submit a raw JSON string in the requst body
+    $client->request(
+        'POST',
+        '/submit',
+        array(),
+        array(),
+        array('CONTENT_TYPE' => 'application/json'),
+        '{"name":"Fabien"}'
+    );
+
     // Form submission with a file upload
     use Symfony\Component\HttpFoundation\File\UploadedFile;
 

components/console/introduction.rst

@@ -160,6 +160,39 @@ You can also set these colors and options inside the tagname::
     // bold text on a yellow background
     $output->writeln('<bg=yellow;options=bold>foo</bg=yellow;options=bold>');
 
+Verbosity Levels
+~~~~~~~~~~~~~~~~
+
+The console has 3 levels of verbosity. These are defined in the
+:class:`Symfony\\Component\\Console\\Output\\OutputInterface`:
+
+==================================  ===============================
+Option                              Value
+==================================  ===============================
+OutputInterface::VERBOSITY_QUIET    Do not output any messages
+OutputInterface::VERBOSITY_NORMAL   The default verbosity level
+OutputInterface::VERBOSITY_VERBOSE  Increased verbosity of messages
+==================================  ===============================
+
+You can specify the quiet verbosity level with the ``--quiet`` or ``-q``
+option. The ``--verbose`` or ``-v`` option is used when you want an increased
+level of verbosity.
+
+.. tip::
+
+    The full exception stacktrace is printed if the ``VERBOSITY_VERBOSE``
+    level is used.
+
+It is possible to print a message in a command for only a specific verbosity
+level. For example::
+
+    if (OutputInterface::VERBOSITY_VERBOSE === $output->getVerbosity()) {
+        $output->writeln(...);
+    }
+
+When the quiet level is used, all output is suppressed as the default
+:method:`Symfony\Component\Console\Output::write<Symfony\\Component\\Console\\Output::write>`
+method returns without actually printing.
 
 Using Command Arguments
 -----------------------

components/dependency_injection/compilation.rst

@@ -316,7 +316,10 @@ something needed in everyday use.
 The compiler pass must have the ``process`` method which is passed the container
 being compiled::
 
-    class CustomCompilerPass
+    use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
+    use Symfony\Component\DependencyInjection\ContainerBuilder;
+
+    class CustomCompilerPass implements CompilerPassInterface
     {
         public function process(ContainerBuilder $container)
         {

components/dom_crawler.rst

@@ -278,16 +278,16 @@ To work with multi-dimensional fields::
         <input name="multi[dimensional]" />
     </form>
 
-You must specify the fully qualified name of the field::
+Pass an array of values::
 
     // Set a single field
-    $form->setValue('multi[0]', 'value');
+    $form->setValues(array('multi' => array('value')));
 
     // Set multiple fields at once
-    $form->setValue('multi', array(
+    $form->setValues(array('multi' => array(
         1             => 'value',
         'dimensional' => 'an other value'
-    ));
+    )));
 
 This is great, but it gets better! The ``Form`` object allows you to interact
 with your form like a browser, selecting radio values, ticking checkboxes,

components/http_foundation/introduction.rst

@@ -406,13 +406,25 @@ represented by a PHP callable instead of a string::
     });
     $response->send();
 
-Downloading Files
-~~~~~~~~~~~~~~~~~
+.. note::
+
+    The ``flush()`` function does not flush buffering. If ``ob_start()`` has
+    been called before or the ``output_buffering`` php.ini option is enabled,
+    you must call ``ob_flush()`` before ``flush()``.
+
+    Additionally, PHP isn't the only layer that can buffer output. Your web
+    server might also buffer based on its configuration. Even more, if you
+    use fastcgi, buffering can't be disabled at all.
+
+.. _component-http-foundation-serving-files:
+
+Serving Files
+~~~~~~~~~~~~~
 
 .. versionadded:: 2.1
     The ``makeDisposition`` method was added in Symfony 2.1.
 
-When uploading a file, you must add a ``Content-Disposition`` header to your
+When sending a file, you must add a ``Content-Disposition`` header to your
 response. While creating this header for basic file downloads is easy, using
 non-ASCII filenames is more involving. The
 :method:`Symfony\\Component\\HttpFoundation\\Response::makeDisposition`
@@ -424,6 +436,33 @@ abstracts the hard work behind a simple API::
 
     $response->headers->set('Content-Disposition', $d);
 
+.. versionadded:: 2.2
+    The :class:`Symfony\\Component\\HttpFoundation\\BinaryFileResponse`
+    class was added in Symfony 2.2.
+
+Alternatively, if you are serving a static file, you can use a
+:class:`Symfony\\Component\\HttpFoundation\\BinaryFileResponse`::
+
+    use Symfony\Component\HttpFoundation\BinaryFileResponse
+    
+    $file = 'path/to/file.txt';
+    $response = new BinaryFileResponse($file);
+
+The ``BinaryFileResponse`` will automatically handle ``Range`` and
+``If-Range`` headers from the request. It also supports ``X-Sendfile``
+(see for `Nginx`_ and `Apache`_). To make use of it, you need to determine
+whether or not the ``X-Sendfile-Type`` header should be trusted and call
+:method:`Symfony\\Component\\HttpFoundation\\BinaryFileResponse::trustXSendfileTypeHeader`
+if it should::
+
+    $response::trustXSendfileTypeHeader();
+
+You can still set the ``Content-Type`` of the sent file, or change its ``Content-Disposition``::
+
+    $response->headers->set('Content-Type', 'text/plain')
+    $response->setContentDisposition(ResponseHeaderBag::DISPOSITION_ATTACHMENT, 'filename.txt');
+    
+
 .. _component-http-foundation-json-response:
 
 Creating a JSON Response
@@ -442,7 +481,8 @@ right content and headers. A JSON response might look like this::
     $response->headers->set('Content-Type', 'application/json');
 
 .. versionadded:: 2.1
-    The :class:`Symfony\\Component\\HttpFoundation\\JsonResponse` class was added in Symfony 2.1.
+    The :class:`Symfony\\Component\\HttpFoundation\\JsonResponse`
+    class was added in Symfony 2.1.
 
 There is also a helpful :class:`Symfony\\Component\\HttpFoundation\\JsonResponse`
 class, which can make this even easier::
@@ -473,3 +513,5 @@ Session
 The session information is in its own document: :doc:`/components/http_foundation/sessions`.
 
 .. _Packagist: https://packagist.org/packages/symfony/http-foundation
+.. _Nginx: http://wiki.nginx.org/XSendfile
+.. _Apache: https://tn123.org/mod_xsendfile/

components/map.rst.inc

@@ -27,7 +27,7 @@
 
   * :doc:`/components/dependency_injection/introduction`
   * :doc:`/components/dependency_injection/types`
-  * :doc:`/components/dependency_injection/parameter`
+  * :doc:`/components/dependency_injection/parameters`
   * :doc:`/components/dependency_injection/definitions`
   * :doc:`/components/dependency_injection/compilation`
   * :doc:`/components/dependency_injection/tags`

components/process.rst

@@ -26,15 +26,16 @@ a command in a sub-process::
     $process = new Process('ls -lsa');
     $process->setTimeout(3600);
     $process->run();
+    
+    // executes after the the command finishes
     if (!$process->isSuccessful()) {
         throw new \RuntimeException($process->getErrorOutput());
     }
 
     print $process->getOutput();
 
-The :method:`Symfony\\Component\\Process\\Process::run` method takes care
-of the subtle differences between the different platforms when executing the
-command.
+The component takes care of the subtle differences between the different platforms
+when executing the command.
 
 .. versionadded:: 2.2
     The ``getIncrementalOutput()`` and ``getIncrementalErrorOutput()`` methods were added in Symfony 2.2.
@@ -60,6 +61,41 @@ anonymous function to the
             echo 'OUT > '.$buffer;
         }
     });
+    
+.. versionadded:: 2.1
+    The non-blocking feature was added in 2.1.
+    
+You can also start the subprocess and then let it run asynchronously, retrieving
+output and the status in your main process whenever you need it. Use the 
+:method:`Symfony\\Component\\Process\\Process::start` method to start an asynchronous
+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->start();
+    
+    while ($process->isRunning()) {
+        // waiting for process to finish
+    }
+
+    echo $process->getOutput();
+    
+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->start();
+    
+    // do other things
+    
+    $process->wait(function ($type, $buffer) {
+        if ('err' === $type) {
+            echo 'ERR > '.$buffer;
+        } else {
+            echo 'OUT > '.$buffer;
+        }
+    });
 
 If you want to execute some PHP code in isolation, use the ``PhpProcess``
 instead::
@@ -73,7 +109,7 @@ instead::
     $process->run();
 
 .. versionadded:: 2.1
-    The ``ProcessBuilder`` class has been as of 2.1.
+    The ``ProcessBuilder`` class was added in Symfony 2.1.
 
 To make your code work better on all platforms, you might want to use the
 :class:`Symfony\\Component\\Process\\ProcessBuilder` class instead::

components/serializer.rst

@@ -93,7 +93,11 @@ use the Serializer service created before::
     $person->setName('foo');
     $person->setAge(99);
 
-    $serializer->serialize($person, 'json'); // Output: {"name":"foo","age":99}
+    $jsonContent = $serializer->serialize($person, 'json');
+
+    // $jsonContent contains {"name":"foo","age":99}
+
+    echo $jsonContent; // or return it in a Response 
 
 The first parameter of the :method:`Symfony\\Component\\Serializer\\Serializer::serialize`
 is the object to be serialized and the second is used to choose the proper encoder,

cookbook/bundles/index.rst

@@ -4,6 +4,7 @@ Bundles
 .. toctree::
     :maxdepth: 2
 
+    installation
     best_practices
     inheritance
     override