Merge branch '2.7' into 2.8

* 2.7: (74 commits)
  Updated doc references in the map.rst.inc file
  Removed the numbers from the file names
  Made a lot of improvements suggested by reviewers
  removed external references alignement
  made some changes to better integrate the tutorial into the current documentation
  fixed markup
  added the new tutorial in the main index
  move things around
  removed versions when adding Symfony component with Composer
  updated the whole book (changes mainly related to Composer)
  Update part06.rst
  updated code for Symfony 2.3 and made minor tweaks to the text
  reworded slightly some sentence to convert the text from a series of articles to a book
  removed unused references
  added missing links
  removed a note that is not relevant anymore
  added an index file
  removed usage of the ClassLoader component in favor of Composer
  updated composer autoload path
  removed the paragraph about CS as we now have standards
  ...

create_framework/dependency-injection.rst

@@ -0,0 +1,243 @@
+The DependencyInjection Component
+=================================
+
+In the previous chapter, we emptied the ``Simplex\Framework`` class by
+extending the ``HttpKernel`` class from the eponymous component. Seeing this
+empty class, you might be tempted to move some code from the front controller
+to it::
+
+    // example.com/src/Simplex/Framework.php
+
+    namespace Simplex;
+
+    use Symfony\Component\Routing;
+    use Symfony\Component\HttpKernel;
+    use Symfony\Component\EventDispatcher\EventDispatcher;
+
+    class Framework extends HttpKernel\HttpKernel
+    {
+        public function __construct($routes)
+        {
+            $context = new Routing\RequestContext();
+            $matcher = new Routing\Matcher\UrlMatcher($routes, $context);
+            $resolver = new HttpKernel\Controller\ControllerResolver();
+
+            $dispatcher = new EventDispatcher();
+            $dispatcher->addSubscriber(new HttpKernel\EventListener\RouterListener($matcher));
+            $dispatcher->addSubscriber(new HttpKernel\EventListener\ResponseListener('UTF-8'));
+
+            parent::__construct($dispatcher, $resolver);
+        }
+    }
+
+The front controller code would become more concise::
+
+    // example.com/web/front.php
+
+    require_once __DIR__.'/../vendor/autoload.php';
+
+    use Symfony\Component\HttpFoundation\Request;
+
+    $request = Request::createFromGlobals();
+    $routes = include __DIR__.'/../src/app.php';
+
+    $framework = new Simplex\Framework($routes);
+
+    $framework->handle($request)->send();
+
+Having a concise front controller allows you to have several front controllers
+for a single application. Why would it be useful? To allow having different
+configuration for the development environment and the production one for
+instance. In the development environment, you might want to have error
+reporting turned on and errors displayed in the browser to ease debugging::
+
+    ini_set('display_errors', 1);
+    error_reporting(-1);
+
+... but you certainly won't want that same configuration on the production
+environment. Having two different front controllers gives you the opportunity
+to have a slightly different configuration for each of them.
+
+So, moving code from the front controller to the framework class makes our
+framework more configurable, but at the same time, it introduces a lot of
+issues:
+
+* We are not able to register custom listeners anymore as the dispatcher is
+  not available outside the Framework class (an easy workaround could be the
+  adding of a ``Framework::getEventDispatcher()`` method);
+
+* We have lost the flexibility we had before; you cannot change the
+  implementation of the ``UrlMatcher`` or of the ``ControllerResolver``
+  anymore;
+
+* Related to the previous point, we cannot test our framework easily anymore
+  as it's impossible to mock internal objects;
+
+* We cannot change the charset passed to ``ResponseListener`` anymore (a
+  workaround could be to pass it as a constructor argument).
+
+The previous code did not exhibit the same issues because we used dependency
+injection; all dependencies of our objects were injected into their
+constructors (for instance, the event dispatchers were injected into the
+framework so that we had total control of its creation and configuration).
+
+Does it mean that we have to make a choice between flexibility, customization,
+ease of testing and not to copy and paste the same code into each application
+front controller? As you might expect, there is a solution. We can solve all
+these issues and some more by using the Symfony dependency injection
+container:
+
+.. code-block:: bash
+
+    $ composer require symfony/dependency-injection
+
+Create a new file to host the dependency injection container configuration::
+
+    // example.com/src/container.php
+
+    use Symfony\Component\DependencyInjection;
+    use Symfony\Component\DependencyInjection\Reference;
+
+    $sc = new DependencyInjection\ContainerBuilder();
+    $sc->register('context', 'Symfony\Component\Routing\RequestContext');
+    $sc->register('matcher', 'Symfony\Component\Routing\Matcher\UrlMatcher')
+        ->setArguments(array($routes, new Reference('context')))
+    ;
+    $sc->register('resolver', 'Symfony\Component\HttpKernel\Controller\ControllerResolver');
+
+    $sc->register('listener.router', 'Symfony\Component\HttpKernel\EventListener\RouterListener')
+        ->setArguments(array(new Reference('matcher')))
+    ;
+    $sc->register('listener.response', 'Symfony\Component\HttpKernel\EventListener\ResponseListener')
+        ->setArguments(array('UTF-8'))
+    ;
+    $sc->register('listener.exception', 'Symfony\Component\HttpKernel\EventListener\ExceptionListener')
+        ->setArguments(array('Calendar\\Controller\\ErrorController::exceptionAction'))
+    ;
+    $sc->register('dispatcher', 'Symfony\Component\EventDispatcher\EventDispatcher')
+        ->addMethodCall('addSubscriber', array(new Reference('listener.router')))
+        ->addMethodCall('addSubscriber', array(new Reference('listener.response')))
+        ->addMethodCall('addSubscriber', array(new Reference('listener.exception')))
+    ;
+    $sc->register('framework', 'Simplex\Framework')
+        ->setArguments(array(new Reference('dispatcher'), new Reference('resolver')))
+    ;
+
+    return $sc;
+
+The goal of this file is to configure your objects and their dependencies.
+Nothing is instantiated during this configuration step. This is purely a
+static description of the objects you need to manipulate and how to create
+them. Objects will be created on-demand when you access them from the
+container or when the container needs them to create other objects.
+
+For instance, to create the router listener, we tell Symfony that its class
+name is ``Symfony\Component\HttpKernel\EventListener\RouterListener``, and
+that its constructor takes a matcher object (``new Reference('matcher')``). As
+you can see, each object is referenced by a name, a string that uniquely
+identifies each object. The name allows us to get an object and to reference
+it in other object definitions.
+
+.. note::
+
+    By default, every time you get an object from the container, it returns
+    the exact same instance. That's because a container manages your "global"
+    objects.
+
+The front controller is now only about wiring everything together::
+
+    // example.com/web/front.php
+
+    require_once __DIR__.'/../vendor/autoload.php';
+
+    use Symfony\Component\HttpFoundation\Request;
+
+    $routes = include __DIR__.'/../src/app.php';
+    $sc = include __DIR__.'/../src/container.php';
+
+    $request = Request::createFromGlobals();
+
+    $response = $sc->get('framework')->handle($request);
+
+    $response->send();
+
+As all the objects are now created in the dependency injection container, the
+framework code should be the previous simple version::
+
+    // example.com/src/Simplex/Framework.php
+
+    namespace Simplex;
+
+    use Symfony\Component\HttpKernel\HttpKernel;
+
+    class Framework extends HttpKernel
+    {
+    }
+
+.. note::
+
+    If you want a light alternative for your container, consider `Pimple`_, a
+    simple dependency injection container in about 60 lines of PHP code.
+
+Now, here is how you can register a custom listener in the front controller::
+
+    $sc->register('listener.string_response', 'Simplex\StringResponseListener');
+    $sc->getDefinition('dispatcher')
+        ->addMethodCall('addSubscriber', array(new Reference('listener.string_response')))
+    ;
+
+Beside describing your objects, the dependency injection container can also be
+configured via parameters. Let's create one that defines if we are in debug
+mode or not::
+
+    $sc->setParameter('debug', true);
+
+    echo $sc->getParameter('debug');
+
+These parameters can be used when defining object definitions. Let's make the
+charset configurable::
+
+    $sc->register('listener.response', 'Symfony\Component\HttpKernel\EventListener\ResponseListener')
+        ->setArguments(array('%charset%'))
+    ;
+
+After this change, you must set the charset before using the response listener
+object::
+
+    $sc->setParameter('charset', 'UTF-8');
+
+Instead of relying on the convention that the routes are defined by the
+``$routes`` variables, let's use a parameter again::
+
+    $sc->register('matcher', 'Symfony\Component\Routing\Matcher\UrlMatcher')
+        ->setArguments(array('%routes%', new Reference('context')))
+    ;
+
+And the related change in the front controller::
+
+    $sc->setParameter('routes', include __DIR__.'/../src/app.php');
+
+We have obviously barely scratched the surface of what you can do with the
+container: from class names as parameters, to overriding existing object
+definitions, from scope support to dumping a container to a plain PHP class,
+and much more. The Symfony dependency injection container is really powerful
+and is able to manage any kind of PHP class.
+
+Don't yell at me if you don't want to use a dependency injection container in
+your framework. If you don't like it, don't use it. It's your framework, not
+mine.
+
+This is (already) the last chapter of this book on creating a framework on top
+of the Symfony components. I'm aware that many topics have not been covered
+in great details, but hopefully it gives you enough information to get started
+on your own and to better understand how the Symfony framework works
+internally.
+
+If you want to learn more, read the source code of the `Silex`_
+micro-framework, and especially its `Application`_ class.
+
+Have fun!
+
+.. _`Pimple`: https://github.com/fabpot/Pimple
+.. _`Silex`: https://silex.sensiolabs.org/
+.. _`Application`: https://github.com/fabpot/Silex/blob/master/src/Silex/Application.php