merged branch TomAdam/pr-update-middleware-doc (PR #725)

This PR was submitted for the master branch but it was merged into the 1.0 branch instead (closes #725).

Discussion
----------

Alter app references in middleware doc

I use ControllerProvider's and functions for my controllers, and I rely on the ````Application```` and ````Request```` being injected via the parameters of each function. Today I happened to need to build some middleware, but found that ````public function before(Application $app)```` resulted in a fatal as the middleware does not use type hinting to set parameters like controllers do. On digging a bit deeper I found in ````Silex\EventListener\MiddlewareListener.php::onKernelRequest```` the following line:
````
$ret = call_user_func($callback, $request, $this->app);
````
This injects application as the second parameter. I'm really happy that it does do this, but the parameter order seems a little strange to me. It's a bit at odds with the rest of the documentation on controllers - the general method prototype is ````method(Application $app, Request $request)````. Given this, I would have expected the app to come first in the parameter list. The same applies to the after callback, except it has ````Response```` between ````Request```` and ````Application````.

The global middleware defined in ````Application```` do not inject the app in any of the callbacks, confusing the matter further. My pattern doesn't actually require this, but some people's might. Is there a reason this hasn't been done? It would be very simple to add, given the three methods are inside the ````Application```` class itself.

The ideal fix to this would be that the middleware use type hinting to apply the parameters, but this is complicated by the callbacks occurring in two classes, neither of which are local to the existing type hinting code. At the very least I think this functionality should be documented, so this is what I have provided in the PR.

Commits
-------

ddc9b92 Alter app references in middleware doc

doc/middlewares.rst

@@ -95,7 +95,7 @@ Before Middleware
 A *before* route middleware is fired just before the route callback, but after
 the *before* application middlewares::
 
-    $before = function (Request $request) use ($app) {
+    $before = function (Request $request, Application $app) {
         // ...
     };
 
@@ -110,7 +110,7 @@ After Middleware
 An *after* route middleware is fired just after the route callback, but before
 the application *after* application middlewares::
 
-    $after = function (Request $request, Response $response) use ($app) {
+    $after = function (Request $request, Response $response, Application $app) {
         // ...
     };