Add documentation for the new BinaryFileResponse class (#1866)

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

components/http_foundation/introduction.rst

@@ -406,13 +406,15 @@ represented by a PHP callable instead of a string::
     });
     $response->send();
 
-Downloading Files
-~~~~~~~~~~~~~~~~~
+.. _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 +426,26 @@ 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. You can also 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 +464,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::