merged branch vicb/sendfile (PR #621)

This PR was merged into the master branch.

Commits
-------

46e6e283 [Doc] Fix references to Symfony 2.0
9eb3b9b2 [Doc] Document Application::sendFile()
570df9d4 implement feedback
734d5738 [Application] Add the ability to send files

Discussion
----------

[Application] Add the ability to send files

---------------------------------------------------------------------------

by GromNaN at 2013-02-06T17:10:24Z

Nice feature 👍

As the `->json` method creates a `JsonResponse`, for consistency the method that create a `BinaryFileResponse` should be named `->binaryFile`.

---------------------------------------------------------------------------

by vicb at 2013-02-06T17:14:43Z

I deeply love consistency but I really can't be consistent with a method named `json` !

---------------------------------------------------------------------------

by vicb at 2013-02-06T18:01:40Z

@igorw will do thanks.

i have also warneed f&j about the test result, subtree split ?

---------------------------------------------------------------------------

by vicb at 2013-02-07T10:29:07Z

@igorw thanks for the feedback, all should be fixed.

---------------------------------------------------------------------------

by fabpot at 2013-02-07T11:26:50Z

Can you add a note in the documentation about this new feature?

---------------------------------------------------------------------------

by vicb at 2013-02-07T12:15:10Z

@fabpot, the doc has been updated

---------------------------------------------------------------------------

by vicb at 2013-02-07T12:23:10Z

@fabpot did you get my email regarding the issue with the tests (sub-stree split ?).

---------------------------------------------------------------------------

by igorw at 2013-02-07T15:45:09Z

Looks good to me. 👍

doc/changelog.rst

 Changelog
 =========
+* **2013-02-07**: added ``Application::sendFile()`` to ease sending
+  ``BinaryFileResponse``.
 
 * **2012-11-05**: Filters have been renamed to application middlewares in the
   documentation.

doc/providers/service_controller.rst

@@ -78,7 +78,7 @@ tested/specced. You may also notice that the only external dependency is on
 ``Symfony\Component\HttpFoundation\JsonResponse``, meaning this controller could
 easily be used in a Symfony (full stack) application, or potentially with other
 applications or frameworks that know how to handle a `Symfony/HttpFoundation
-<http://symfony.com/doc/2.0/components/http_foundation/introduction.html>`_
+<http://symfony.com/doc/master/components/http_foundation/introduction.html>`_
 ``Response`` object.
 
 .. code-block:: php

doc/providers/validator.rst

@@ -221,4 +221,4 @@ provider and register the messages under the ``validators`` domain::
     );
 
 For more information, consult the `Symfony2 Validation documentation
-<http://symfony.com/doc/2.0/book/validation.html>`_.
+<http://symfony.com/doc/master/book/validation.html>`_.

doc/usage.rst

@@ -614,6 +614,35 @@ after every chunk::
         fclose($fh);
     };
 
+Sending a file
+--------------
+
+If you want to return a file, you can use the ``sendFile`` helper method.
+It eases returning files that would otherwise not be publicly available. Simply
+pass it your file path, status code, headers and the content disposition and it
+will create a ``BinaryFileResponse`` based response for you::
+
+    $app->get('/files/{path}', function ($path) use ($app) {
+        if (!file_exists('/base/path/' . $path)) {
+            $app->abort(404);
+        }
+
+        return $app->sendFile('/base/path/' . $path);
+    });
+
+To further customize the response before returning it, check the API doc for
+`Symfony\Component\HttpFoundation\BinaryFileResponse
+<http://api.symfony.com/master/Symfony/Component/HttpFoundation/BinaryFileResponse.html>`_::
+
+    return $app
+        ->sendFile('/base/path/' . $path)
+        ->setContentDisposition(ResponseHeaderBag::DISPOSITION_ATTACHMENT, 'pic.jpg')
+    ;
+
+.. note::
+
+    Http Foundation 2.2 or greater is required for this feature to be available.
+
 Traits
 ------
 

src/Silex/Application.php

@@ -11,6 +11,7 @@
 
 namespace Silex;
 
+use Symfony\Component\HttpFoundation\BinaryFileResponse;
 use Symfony\Component\HttpKernel\HttpKernel;
 use Symfony\Component\HttpKernel\HttpKernelInterface;
 use Symfony\Component\HttpKernel\TerminableInterface;
@@ -422,6 +423,27 @@ class Application extends \Pimple implements HttpKernelInterface, TerminableInte
         return new JsonResponse($data, $status, $headers);
     }
 
+    /**
+     * Sends a file.
+     *
+     * @param \SplFileInfo|string $file               The file to stream
+     * @param integer             $status             The response status code
+     * @param array               $headers            An array of response headers
+     * @param null|string         $contentDisposition The type of Content-Disposition to set automatically with the filename
+     *
+     * @return BinaryFileResponse
+     *
+     * @throws \RuntimeException When the feature is not supported, before http-foundation v2.2
+     */
+    public function sendFile($file, $status = 200, $headers = array(), $contentDisposition = null)
+    {
+        if (!class_exists('Symfony\Component\HttpFoundation\BinaryFileResponse')) {
+            throw new \RuntimeException('The "senfFile" method is only supported as of Http Foundation 2.2.');
+        }
+
+        return new BinaryFileResponse($file, $status, $headers, true, $contentDisposition);
+    }
+
     /**
      * Mounts controllers under the given route prefix.
      *

tests/Silex/Tests/ApplicationTest.php

@@ -487,6 +487,19 @@ class ApplicationTest extends \PHPUnit_Framework_TestCase
 
         $this->assertSame($app, $app->mount('/hello', $mounted));
     }
+
+    public function testSendFile()
+    {
+        $app = new Application();
+
+        try {
+            $response = $app->sendFile(__FILE__, 200, array('Content-Type: application/php'));
+            $this->assertInstanceOf('Symfony\Component\HttpFoundation\BinaryFileResponse', $response);
+            $this->assertEquals(__FILE__, (string) $response->getFile());
+        } catch (\RuntimeException $e) {
+            $this->assertFalse(class_exists('Symfony\Component\HttpFoundation\BinaryFileResponse'));
+        }
+    }
 }
 
 class FooController