made some changes to better integrate the tutorial into the current documentation

Author: fabpot

create_framework/01-introduction.rst

@@ -8,19 +8,14 @@ Instead of using these low-level components, you can use the ready-to-be-used
 Symfony2 full-stack web framework, which is based on these components... or
 you can create your very own framework. This book is about the latter.
 
-.. note::
-
-    If you just want to use the Symfony2 full-stack framework, you'd better
-    read its official `documentation`_ instead.
-
 Why would you like to create your own framework?
 ------------------------------------------------
 
 Why would you like to create your own framework in the first place? If you
 look around, everybody will tell you that it's a bad thing to reinvent the
 wheel and that you'd better choose an existing framework and forget about
-creating your own altogether. Most of the time, they are right but I can think
-of a few good reasons to start creating your own framework:
+creating your own altogether. Most of the time, they are right but there are
+a few good reasons to start creating your own framework:
 
 * To learn more about the low level architecture of modern web frameworks in
   general and about the Symfony2 full-stack framework internals in particular;
@@ -37,11 +32,11 @@ of a few good reasons to start creating your own framework:
 * To prove the world that you can actually create a framework on your own (...
   but with little effort).
 
-I will gently guide you through the creation of a web framework, one step at a
-time. At each step, you will have a fully-working framework that you can use
-as is or as a start for your very own. We will start with simple frameworks
-and more features will be added with time. Eventually, you will have a
-fully-featured full-stack web framework.
+This tutorial will gently guide you through the creation of a web framework,
+one step at a time. At each step, you will have a fully-working framework that
+you can use as is or as a start for your very own. We will start with simple
+frameworks and more features will be added with time. Eventually, you will have
+a fully-featured full-stack web framework.
 
 And of course, each step will be the occasion to learn more about some of the
 Symfony2 Components.
@@ -58,16 +53,16 @@ won't talk about the MVC pattern as the Symfony2 Components are able to create
 any type of frameworks, not just the ones that follow the MVC architecture.
 Anyway, if you have a look at the MVC semantics, this book is about how to
 create the Controller part of a framework. For the Model and the View, it
-really depends on your personal taste and I will let you use any existing
+really depends on your personal taste and you can use any existing
 third-party libraries (Doctrine, Propel, or plain-old PDO for the Model; PHP
 or Twig for the View).
 
-When creating a framework, following the MVC pattern is not the right goal.
-The main goal should be the **Separation of Concerns**; I actually think that
-this is the only design pattern that you should really care about. The
-fundamental principles of the Symfony2 Components are focused on the HTTP
-specification. As such, the frameworks that we are going to create should be
-more accurately labelled as HTTP frameworks or Request/Response frameworks.
+When creating a framework, following the MVC pattern is not the right goal. The
+main goal should be the **Separation of Concerns**; this is probably the only
+design pattern that you should really care about. The fundamental principles of
+the Symfony2 Components are focused on the HTTP specification. As such, the
+frameworks that we are going to create should be more accurately labelled as
+HTTP frameworks or Request/Response frameworks.
 
 Before we start
 ---------------
@@ -89,7 +84,7 @@ classes, how we will reference external dependencies, etc.
 
 To store our framework, create a directory somewhere on your machine:
 
-.. code-block:: sh
+.. code-block:: bash
 
     $ mkdir framework
     $ cd framework
@@ -101,16 +96,16 @@ To install the Symfony2 Components that we need for our framework, we are going
 to use `Composer`_, a project dependency manager for PHP. If you don't have it
 yet, `download and install`_ Composer now:
 
-.. code-block:: sh
+.. code-block:: bash
 
     $ curl -sS https://getcomposer.org/installer | php
 
 Then, generate an empty ``composer.json`` file, where Composer will store the
 framework dependencies:
 
-.. code-block:: sh
+.. code-block:: bash
 
-    $ php composer.phar init -n
+    $ composer init -n
 
 Our Project
 -----------
@@ -130,7 +125,7 @@ start with the simplest web application we can think of in PHP::
 Use the PHP built-in server to test this great application in a browser
 (``http://localhost:4321/index.php?name=Fabien``):
 
-.. code-block:: sh
+.. code-block:: bash
 
     $ php -S 127.0.0.1:4321
 

create_framework/02-http-foundation.rst

@@ -1,16 +1,15 @@
 The HttpFoundation Component
 ============================
 
-Before diving into the framework creation process, I first want to step back
-and take a look at why you would like to use a framework instead of keeping
-your plain-old PHP applications as is. Why using a framework is actually a
-good idea, even for the simplest snippet of code and why creating your
-framework on top of the Symfony2 components is better than creating a
-framework from scratch.
+Before diving into the framework creation process, let's first step back and
+let's take a look at why you would like to use a framework instead of keeping
+your plain-old PHP applications as is. Why using a framework is actually a good
+idea, even for the simplest snippet of code and why creating your framework on
+top of the Symfony2 components is better than creating a framework from scratch.
 
 .. note::
 
-    I won't talk about the obvious and traditional benefits of using a
+    We won't talk about the obvious and traditional benefits of using a
     framework when working on big applications with more than a few
     developers; the Internet has already plenty of good resources on that
     topic.
@@ -124,9 +123,9 @@ layer.
 
 To use this component, add it as a dependency of the project:
 
-.. code-block:: sh
+.. code-block:: bash
 
-    $ php composer.phar require symfony/http-foundation
+    $ composer require symfony/http-foundation
 
 Running this command will also automatically download the Symfony
 HttpFoundation component and install it under the ``vendor/`` directory.
@@ -270,13 +269,12 @@ chained proxies)::
         // the client is a known one, so give it some more privilege
     }
 
-And there is an added benefit: it is *secure* by default. What do I mean by
-secure? The ``$_SERVER['HTTP_X_FORWARDED_FOR']`` value cannot be trusted as it
-can be manipulated by the end user when there is no proxy. So, if you are
-using this code in production without a proxy, it becomes trivially easy to
-abuse your system. That's not the case with the ``getClientIp()`` method as
-you must explicitly trust your reverse proxies by calling
-``setTrustedProxies()``::
+And there is an added benefit: it is *secure* by default. What does it mean?
+The ``$_SERVER['HTTP_X_FORWARDED_FOR']`` value cannot be trusted as it can be
+manipulated by the end user when there is no proxy. So, if you are using this
+code in production without a proxy, it becomes trivially easy to abuse your
+system. That's not the case with the ``getClientIp()`` method as you must
+explicitly trust your reverse proxies by calling ``setTrustedProxies()``::
 
     <?php
 
@@ -295,8 +293,8 @@ cases by yourself. Why not using a technology that already works?
 .. note::
 
     If you want to learn more about the HttpFoundation component, you can have
-    a look at the `API`_ or read its dedicated `documentation`_ on the Symfony
-    website.
+    a look at the :namespace:`Symfony\\Component\\HttpFoundation` API or read
+    its dedicated :doc:`documentation </components/http_foundation/index>`.
 
 Believe or not but we have our first framework. You can stop now if you want.
 Using just the Symfony2 HttpFoundation component already allows you to write
@@ -315,8 +313,6 @@ applications using it (like `Symfony2`_, `Drupal 8`_, `phpBB 4`_, `ezPublish
 .. _`Twig`:                     http://twig.sensiolabs.com/
 .. _`Symfony2 versus Flat PHP`: http://symfony.com/doc/current/book/from_flat_php_to_symfony2.html
 .. _`HTTP specification`:       http://tools.ietf.org/wg/httpbis/
-.. _`API`:                      http://api.symfony.com/2.0/Symfony/Component/HttpFoundation.html
-.. _`documentation`:            http://symfony.com/doc/current/components/http_foundation.html
 .. _`audited`:                  http://symfony.com/blog/symfony2-security-audit
 .. _`Symfony2`:                 http://symfony.com/
 .. _`Drupal 8`:                 http://drupal.org/

create_framework/03-front-controller.rst

@@ -172,7 +172,7 @@ other files won't be accessible from the client anymore.
 To test your changes in a browser (``http://localhost:4321/?name=Fabien``), run
 the PHP built-in server:
 
-.. code-block:: sh
+.. code-block:: bash
 
     $ php -S 127.0.0.1:4321 -t web/ web/front.php
 

create_framework/04-routing.rst

@@ -55,9 +55,9 @@ instead of relying on a query string:
 
 To support this feature, add the Symfony2 Routing component as a dependency:
 
-.. code-block:: sh
+.. code-block:: bash
 
-    $ php composer.phar require symfony/routing
+    $ composer require symfony/routing
 
 Instead of an array for the URL map, the Routing component relies on a
 ``RouteCollection`` instance::

create_framework/06-http-kernel.rst

@@ -39,9 +39,9 @@ instantiated.
 To solve this issue, and a bunch more, let's install and use the HttpKernel
 component:
 
-.. code-block:: sh
+.. code-block:: bash
 
-    $ php composer.phar require symfony/http-kernel
+    $ composer require symfony/http-kernel
 
 The HttpKernel component has many interesting features, but the one we need
 right now is the *controller resolver*. A controller resolver knows how to

create_framework/07-separation-of-concerns.rst

@@ -98,7 +98,7 @@ be autoloaded, update the ``composer.json`` file:
 
 .. note::
 
-    For the Composer autoloader to be updated, run ``php composer.phar update``.
+    For the Composer autoloader to be updated, run ``composer update``.
 
 Move the controller to ``Calendar\\Controller\\LeapYearController``::
 

create_framework/08-unit-testing.rst

@@ -119,9 +119,8 @@ Executing this test is as simple as running ``phpunit`` from the
 
 .. note::
 
-    I do not explain how the code works in details as this is not the goal of
-    this book, but if you don't understand what the hell is going on, I highly
-    recommend you to read PHPUnit documentation on `test doubles`_.
+    If you don't understand what the hell is going on in the code, read
+    PHPUnit documentation on `test doubles`_.
 
 After the test ran, you should see a green bar. If not, you have a bug
 either in the test or in the framework code!

create_framework/09-event-dispatcher.rst

@@ -17,9 +17,9 @@ pattern, the *Observer*, to allow any kind of behaviors to be attached to our
 framework; the Symfony2 EventDispatcher Component implements a lightweight
 version of this pattern:
 
-.. code-block:: sh
+.. code-block:: bash
 
-    $ php composer.phar require symfony/event-dispatcher
+    $ composer require symfony/event-dispatcher
 
 How does it work? The *dispatcher*, the central object of the event dispatcher
 system, notifies *listeners* of an *event* dispatched to it. Put another way:
@@ -165,7 +165,7 @@ type is HTML (these conditions demonstrate the ease of manipulating the
 Request and Response data from your code).
 
 So far so good, but let's add another listener on the same event. Let's say
-that I want to set the ``Content-Length`` of the Response if it is not already
+that we want to set the ``Content-Length`` of the Response if it is not already
 set::
 
     $dispatcher->addListener('response', function (Simplex\ResponseEvent $event) {

create_framework/10-http-kernel.rst

@@ -99,8 +99,8 @@ content and check that the number only changes every 10 seconds::
 Using HTTP cache headers to manage your application cache is very powerful and
 allows you to tune finely your caching strategy as you can use both the
 expiration and the validation models of the HTTP specification. If you are not
-comfortable with these concepts, I highly recommend you to read the `HTTP
-caching`_ chapter of the Symfony2 documentation.
+comfortable with these concepts, read the `HTTP caching`_ chapter of the
+Symfony2 documentation.
 
 The Response class contains many other methods that let you configure the
 HTTP cache very easily. One of the most powerful is ``setCache()`` as it

create_framework/12-dependency-injection.rst

@@ -91,9 +91,9 @@ front controller? As you might expect, there is a solution. We can solve all
 these issues and some more by using the Symfony2 dependency injection
 container:
 
-.. code-block:: sh
+.. code-block:: bash
 
-    $ php composer.phar require symfony/dependency-injection
+    $ composer require symfony/dependency-injection
 
 Create a new file to host the dependency injection container configuration::
 
@@ -243,8 +243,8 @@ in great details, but hopefully it gives you enough information to get started
 on your own and to better understand how the Symfony2 framework works
 internally.
 
-If you want to learn more, I highly recommend you to read the source code of
-the `Silex`_ micro-framework, and especially its `Application`_ class.
+If you want to learn more, read the source code of the `Silex`_
+micro-framework, and especially its `Application`_ class.
 
 Have fun!