Made a lot of improvements suggested by reviewers

Author: javiereguiluz

create_framework/01-introduction.rst

@@ -1,14 +1,14 @@
 Introduction
 ============
 
-`Symfony2`_ is a reusable set of standalone, decoupled, and cohesive PHP
+`Symfony`_ is a reusable set of standalone, decoupled and cohesive PHP
 components that solve common web development problems.
 
 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.
+Symfony full-stack web framework, which is based on these components... or
+you can create your very own framework. This tutorial is about the latter.
 
-Why would you like to create your own framework?
+Why would you Like to Create your Own Framework?
 ------------------------------------------------
 
 Why would you like to create your own framework in the first place? If you
@@ -18,7 +18,7 @@ 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;
+  general and about the Symfony full-stack framework internals in particular;
 
 * To create a framework tailored to your very specific needs (just be sure
   first that your needs are really specific);
@@ -34,55 +34,55 @@ a few good reasons to start creating your own 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
+you can use as is or as a start for your very own. It will start with a simple
+framework 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.
+Symfony Components.
 
 .. tip::
 
     If you don't have time to read the whole book, or if you want to get
     started fast, you can also have a look at `Silex`_, a micro-framework
-    based on the Symfony2 Components. The code is rather slim and it leverages
-    many aspects of the Symfony2 Components.
-
-Many modern web frameworks advertize themselves as being MVC frameworks. We
-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 you can use any existing
-third-party libraries (Doctrine, Propel, or plain-old PDO for the Model; PHP
-or Twig for the View).
+    based on the Symfony Components. The code is rather slim and it leverages
+    many aspects of the Symfony Components.
+
+Many modern web frameworks advertize themselves as being MVC frameworks. This
+tutorial won't talk about the MVC pattern, as the Symfony 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 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**; 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.
+the Symfony Components are focused on the HTTP specification. As such, the
+framework that you are going to create should be more accurately labelled as a
+HTTP framework or Request/Response framework.
 
-Before we start
----------------
+Before You Start
+----------------
 
 Reading about how to create a framework is not enough. You will have to follow
-along and actually type all the examples we will work on. For that, you need a
-recent version of PHP (5.3.8 or later is good enough), a web server (like
-Apache or NGinx), a good knowledge of PHP and an understanding of Object
-Oriented programming.
+along and actually type all the examples included in this tutorial. For that,
+you need a recent version of PHP (5.3.9 or later is good enough), a web server
+(like Apache, NGinx or PHP's built-in web server), a good knowledge of PHP and
+an understanding of Object Oriented programming.
 
-Ready to go? Let's start.
+Ready to go? Read on!
 
 Bootstrapping
 -------------
 
-Before we can even think of creating our first framework, we need to talk
-about some conventions: where we will store our code, how we will name our
-classes, how we will reference external dependencies, etc.
+Before you can even think of creating the first framework, you need to think
+about some conventions: where you will store the code, how you will name the
+classes, how you will reference external dependencies, etc.
 
-To store our framework, create a directory somewhere on your machine:
+To store your new framework, create a directory somewhere on your machine:
 
 .. code-block:: bash
 
@@ -92,20 +92,9 @@ To store our framework, create a directory somewhere on your machine:
 Dependency Management
 ~~~~~~~~~~~~~~~~~~~~~
 
-To install the Symfony2 Components that we need for our framework, we are going
+To install the Symfony Components that you need for your framework, you 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:: bash
-
-    $ curl -sS https://getcomposer.org/installer | php
-
-Then, generate an empty ``composer.json`` file, where Composer will store the
-framework dependencies:
-
-.. code-block:: bash
-
-    $ composer init -n
+yet, :doc:`download and install Composer </cookbook/composer>` now.
 
 Our Project
 -----------
@@ -114,16 +103,15 @@ Instead of creating our framework from scratch, we are going to write the same
 "application" over and over again, adding one abstraction at a time. Let's
 start with the simplest web application we can think of in PHP::
 
-    <?php
-
     // framework/index.php
 
     $input = $_GET['name'];
 
     printf('Hello %s', $input);
 
-Use the PHP built-in server to test this great application in a browser
-(``http://localhost:4321/index.php?name=Fabien``):
+If you have PHP 5.4, you can use the PHP built-in server to test this great
+application in a browser (``http://localhost:4321/index.php?name=Fabien``).
+Otherwise, use your own server (Apache, Nginx, etc.):
 
 .. code-block:: bash
 
@@ -132,8 +120,7 @@ Use the PHP built-in server to test this great application in a browser
 In the next chapter, we are going to introduce the HttpFoundation Component
 and see what it brings us.
 
-.. _`Symfony2`: http://symfony.com/
+.. _`Symfony`: http://symfony.com/
 .. _`documentation`: http://symfony.com/doc
 .. _`Silex`: http://silex.sensiolabs.org/
 .. _`Composer`: http://packagist.org/about-composer
-.. _`download and install`: https://getcomposer.org/doc/01-basic-usage.md

create_framework/02-http-foundation.rst

@@ -5,7 +5,7 @@ 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.
+top of the Symfony components is better than creating a framework from scratch.
 
 .. note::
 
@@ -17,8 +17,6 @@ top of the Symfony2 components is better than creating a framework from scratch.
 Even if the "application" we wrote in the previous chapter was simple enough,
 it suffers from a few problems::
 
-    <?php
-
     // framework/index.php
 
     $input = $_GET['name'];
@@ -28,8 +26,6 @@ it suffers from a few problems::
 First, if the ``name`` query parameter is not defined in the URL query string,
 you will get a PHP warning; so let's fix it::
 
-    <?php
-
     // framework/index.php
 
     $input = isset($_GET['name']) ? $_GET['name'] : 'World';
@@ -40,8 +36,6 @@ Then, this *application is not secure*. Can you believe it? Even this simple
 snippet of PHP code is vulnerable to one of the most widespread Internet
 security issue, XSS (Cross-Site Scripting). Here is a more secure version::
 
-    <?php
-
     $input = isset($_GET['name']) ? $_GET['name'] : 'World';
 
     header('Content-Type: text/html; charset=utf-8');
@@ -65,8 +59,6 @@ much to test, it strikes me that writing unit tests for the simplest possible
 snippet of PHP code is not natural and feels ugly. Here is a tentative PHPUnit
 unit test for the above code::
 
-    <?php
-
     // framework/test.php
 
     class IndexTest extends \PHPUnit_Framework_TestCase
@@ -86,8 +78,8 @@ unit test for the above code::
 .. note::
 
     If our application were just slightly bigger, we would have been able to
-    find even more problems. If you are curious about them, read the `Symfony2
-    versus Flat PHP`_ chapter of the Symfony2 documentation.
+    find even more problems. If you are curious about them, read the `Symfony
+    versus Flat PHP`_ chapter of the Symfony documentation.
 
 At this point, if you are not convinced that security and testing are indeed
 two very good reasons to stop writing code the old way and adopt a framework
@@ -117,7 +109,7 @@ In PHP, the request is represented by global variables (``$_GET``, ``$_POST``,
 functions (``echo``, ``header``, ``setcookie``, ...).
 
 The first step towards better code is probably to use an Object-Oriented
-approach; that's the main goal of the Symfony2 HttpFoundation component:
+approach; that's the main goal of the Symfony HttpFoundation component:
 replacing the default PHP global variables and functions by an Object-Oriented
 layer.
 
@@ -141,8 +133,6 @@ HttpFoundation component and install it under the ``vendor/`` directory.
 Now, let's rewrite our application by using the ``Request`` and the
 ``Response`` classes::
 
-    <?php
-
     // framework/index.php
 
     require_once __DIR__.'/vendor/autoload.php';
@@ -184,8 +174,6 @@ charge of sending the response whenever you see fit.
 With the ``Request`` class, you have all the request information at your
 fingertips thanks to a nice and simple API::
 
-    <?php
-
     // the URI being requested (e.g. /about) minus any query parameters
     $request->getPathInfo();
 
@@ -215,8 +203,6 @@ You can also simulate a request::
 
 With the ``Response`` class, you can easily tweak the response::
 
-    <?php
-
     $response = new Response();
 
     $response->setContent('Hello world!');
@@ -240,8 +226,6 @@ framework?
 
 Even something as simple as getting the client IP address can be insecure::
 
-    <?php
-
     if ($myIp == $_SERVER['REMOTE_ADDR']) {
         // the client is a known one, so give it some more privilege
     }
@@ -251,8 +235,6 @@ production servers; at this point, you will have to change your code to make
 it work on both your development machine (where you don't have a proxy) and
 your servers::
 
-    <?php
-
     if ($myIp == $_SERVER['HTTP_X_FORWARDED_FOR'] || $myIp == $_SERVER['REMOTE_ADDR']) {
         // the client is a known one, so give it some more privilege
     }
@@ -261,8 +243,6 @@ Using the ``Request::getClientIp()`` method would have given you the right
 behavior from day one (and it would have covered the case where you have
 chained proxies)::
 
-    <?php
-
     $request = Request::createFromGlobals();
 
     if ($myIp == $request->getClientIp()) {
@@ -276,8 +256,6 @@ 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
-
     Request::setTrustedProxies(array('10.0.0.1'));
 
     if ($myIp == $request->getClientIp(true)) {
@@ -297,7 +275,7 @@ cases by yourself. Why not using a technology that already works?
     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
+Using just the Symfony HttpFoundation component already allows you to write
 better and more testable code. It also allows you to write code faster as many
 day-to-day problems have already been solved for you.
 
@@ -307,14 +285,14 @@ the wheel.
 
 I've almost forgot to talk about one added benefit: using the HttpFoundation
 component is the start of better interoperability between all frameworks and
-applications using it (like `Symfony2`_, `Drupal 8`_, `phpBB 4`_, `ezPublish
+applications using it (like `Symfony`_, `Drupal 8`_, `phpBB 4`_, `ezPublish
 5`_, `Laravel`_, `Silex`_, and `more`_).
 
 .. _`Twig`: http://twig.sensiolabs.com/
-.. _`Symfony2 versus Flat PHP`: http://symfony.com/doc/current/book/from_flat_php_to_symfony2.html
+.. _`Symfony versus Flat PHP`: http://symfony.com/doc/current/book/from_flat_php_to_symfony2.html
 .. _`HTTP specification`: http://tools.ietf.org/wg/httpbis/
 .. _`audited`: http://symfony.com/blog/symfony2-security-audit
-.. _`Symfony2`: http://symfony.com/
+.. _`Symfony`: http://symfony.com/
 .. _`Drupal 8`: http://drupal.org/
 .. _`phpBB 4`: http://www.phpbb.com/
 .. _`ezPublish 5`: http://ez.no/

create_framework/03-front-controller.rst

@@ -5,8 +5,6 @@ Up until now, our application is simplistic as there is only one page. To
 spice things up a little bit, let's go crazy and add another page that says
 goodbye::
 
-    <?php
-
     // framework/bye.php
 
     require_once __DIR__.'/vendor/autoload.php';
@@ -27,8 +25,6 @@ our first "real" framework!
 The PHP way of doing the refactoring would probably be the creation of an
 include file::
 
-    <?php
-
     // framework/init.php
 
     require_once __DIR__.'/vendor/autoload.php';
@@ -41,8 +37,6 @@ include file::
 
 Let's see it in action::
 
-    <?php
-
     // framework/index.php
 
     require_once __DIR__.'/init.php';
@@ -54,8 +48,6 @@ Let's see it in action::
 
 And for the "Goodbye" page::
 
-    <?php
-
     // framework/bye.php
 
     require_once __DIR__.'/init.php';
@@ -83,8 +75,6 @@ routing all client requests to a single PHP script.
 
 Such a script might look like the following::
 
-    <?php
-
     // framework/front.php
 
     require_once __DIR__.'/vendor/autoload.php';
@@ -112,8 +102,6 @@ Such a script might look like the following::
 
 And here is for instance the new ``hello.php`` script::
 
-    <?php
-
     // framework/hello.php
 
     $input = $request->get('name', 'World');
@@ -185,8 +173,6 @@ The last thing that is repeated in each page is the call to ``setContent()``.
 We can convert all pages to "templates" by just echoing the content and calling
 the ``setContent()`` directly from the front controller script::
 
-    <?php
-
     // example.com/web/front.php
 
     // ...
@@ -213,8 +199,6 @@ And the ``hello.php`` script can now be converted to a template::
 
 We have the first version of our framework::
 
-    <?php
-
     // example.com/web/front.php
 
     require_once __DIR__.'/../vendor/autoload.php';