Merge branch '2.5' into 2.6

* 2.5: (30 commits)
  Update forms.rst
  link to the API documentation
  Re-wording parameters.yml section and removing note about vendor #4608
  [#4608] Using #. for numbered bullets
  Changing and -> or based on conversation in #4532
  Changed to definition lists from Book section
  Changed to definition lists
  Fixed heading capitalization to follow the standards
  Changed paragraph to heading
  Changed unordered list to definition list
  Spelling mistake tens to tons
  Removed double `firewall_restriction` entry
  Normalize the method listings on version 2.5
  Update controllers.rst
  Update the_controller.rst
  replace Symfony2 with Symfony
  Linked the PDO/DBAL Session article from the Doctrine category
  Fix indentation of YAML example
  Fixed some code indentation
  Fixed section headers
  ...

Author: weaverryan

best_practices/controllers.rst

@@ -136,6 +136,8 @@ For example:
 
 .. code-block:: php
 
+    use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
+    
     /**
      * @Route("/{id}", name="admin_post_show")
      */

best_practices/creating-the-project.rst

@@ -4,50 +4,39 @@ Creating the Project
 Installing Symfony
 ------------------
 
-There is only one recommended way to install Symfony:
+In the past, Symfony projects were created with `Composer`_, the dependency manager
+for PHP applications. However, the current recommendation is to use the **Symfony
+Installer**, which has to be installed before creating your first project.
 
-.. best-practice::
-
-    Always use `Composer`_ to install Symfony.
-
-Composer is the dependency manager used by modern PHP applications. Adding or
-removing requirements for your project and updating the third-party libraries
-used by your code is a breeze thanks to Composer.
-
-Dependency Management with Composer
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Linux and Mac OS X Systems
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Before installing Symfony, you need to make sure that you have Composer installed
-globally. Open your terminal (also called *command console*) and run the following
-command:
+Open your command console and execute the following:
 
 .. code-block:: bash
 
-    $ composer --version
-    Composer version 1e27ff5e22df81e3cd0cd36e5fdd4a3c5a031f4a 2014-08-11 15:46:48
+    $ curl -LsS http://symfony.com/installer > symfony.phar
+    $ sudo mv symfony.phar /usr/local/bin/symfony
+    $ chmod a+x /usr/local/bin/symfony
 
-You'll probably see a different version identifier. Never mind because Composer
-is updated on a continuous basis and its specific version doesn't matter.
+Now you can execute the Symfony Installer as a global system command called
+``symfony``.
 
-Installing Composer Globally
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Windows Systems
+~~~~~~~~~~~~~~~
 
-In case you don't have Composer installed globally, execute the following two
-commands if you use Linux or Mac OS X (the second command will ask for your
-user password):
+Open your command console and execute the following:
 
 .. code-block:: bash
 
-    $ curl -sS https://getcomposer.org/installer | php
-    $ sudo mv composer.phar /usr/local/bin/composer
+    c:\> php -r "readfile('http://symfony.com/installer');" > symfony.phar
 
-.. note::
+Then, move the downloaded ``symfony.phar`` file to your projects directory and
+execute it as follows:
 
-    Depending on your Linux distribution, you may need to execute ``su`` command
-    instead of ``sudo``.
+.. code-block:: bash
 
-If you use a Windows system, download the executable installer from the
-`Composer download page`_ and follow the steps to install it.
+    c:\> php symfony.phar
 
 Creating the Blog Application
 -----------------------------
@@ -58,64 +47,19 @@ to create files and execute the following commands:
 
 .. code-block:: bash
 
+    # Linux, Mac OS X
     $ cd projects/
-    $ composer create-project symfony/framework-standard-edition blog/
-
-This command will create a new directory called ``blog`` that will contain
-a fresh new project based on the most recent stable Symfony version available.
-
-Checking the Symfony Installation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Once the installation is finished, enter the ``blog/`` directory and check that
-Symfony is correctly installed by executing the following command:
-
-.. code-block:: bash
-
-    $ cd blog/
-    $ php app/console --version
-
-    Symfony version 2.6.* - app/dev/debug
-
-If you see the installed Symfony version, everything worked as expected. If not,
-you can execute the following *script* to check what does prevent your system
-from correctly executing Symfony applications:
-
-.. code-block:: bash
-
-    $ php app/check.php
-
-Depending on your system, you can see up to two different lists when executing the
-`check.php` script. The first one shows the mandatory requirements which your
-system must meet to execute Symfony applications. The second list shows the
-optional requirements suggested for an optimal execution of Symfony applications:
-
-.. code-block:: bash
-
-    Symfony2 Requirements Checker
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-    > PHP is using the following php.ini file:
-      /usr/local/zend/etc/php.ini
-
-    > Checking Symfony requirements:
-      .....E.........................W.....
-
-    [ERROR]
-    Your system is not ready to run Symfony2 projects
-
-    Fix the following mandatory requirements
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-     * date.timezone setting must be set
-       > Set the "date.timezone" setting in php.ini* (like Europe/Paris).
-
-    Optional recommendations to improve your setup
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    $ symfony new blog
 
-     * short_open_tag should be disabled in php.ini
-       > Set short_open_tag to off in php.ini*.
+    # Windows
+    c:\> cd projects/
+    c:\projects\> php symfony.phar new blog
 
+This command creates a new directory called ``blog`` that contains a fresh new
+project based on the most recent stable Symfony version available. In addition,
+the installer checks if your system meets the technical requirements to execute
+Symfony applications. If not, you'll see the list of changes needed to meet those
+requirements.
 
 .. tip::
 
@@ -243,7 +187,7 @@ it's released:
     └─ web/
 
 The changes are pretty superficial, but for now, we recommend that you use
-the Symfony2 directory structure.
+the Symfony directory structure.
 
 .. _`Composer`: https://getcomposer.org/
 .. _`Get Started`: https://getcomposer.org/doc/00-intro.md

best_practices/forms.rst

@@ -14,7 +14,7 @@ Building Forms
 
 The Form component allows you to build forms right inside your controller
 code. Honestly, unless you need to reuse the form somewhere else, that's
-totally fine. But for organize and reuse, we recommend that you define each
+totally fine. But for organization and reuse, we recommend that you define each
 form in its own PHP class::
 
     namespace AppBundle\Form;

best_practices/security.rst

@@ -336,7 +336,7 @@ Learn More
 ----------
 
 The `FOSUserBundle`_, developed by the Symfony community, adds support for a
-database-backed user system in Symfony2. It also handles common tasks like
+database-backed user system in Symfony. It also handles common tasks like
 user registration and forgotten password functionality.
 
 Enable the :doc:`Remember Me feature </cookbook/security/remember_me>` to

book/forms.rst

@@ -716,14 +716,16 @@ the correct values of a number of field options.
     And though you'll need to manually add your server-side validation, these
     field type options can then be guessed from that information.
 
-* ``required``: The ``required`` option can be guessed based on the validation
-  rules (i.e. is the field ``NotBlank`` or ``NotNull``) or the Doctrine metadata
-  (i.e. is the field ``nullable``). This is very useful, as your client-side
-  validation will automatically match your validation rules.
+``required``
+    The ``required`` option can be guessed based on the validation rules (i.e. is
+    the field ``NotBlank`` or ``NotNull``) or the Doctrine metadata (i.e. is the
+    field ``nullable``). This is very useful, as your client-side validation will
+    automatically match your validation rules.
 
-* ``maxlength``: If the field is some sort of text field, then the ``maxlength``
-  option attribute can be guessed from the validation constraints (if ``Length`` or
-  ``Range`` is used) or from the Doctrine metadata (via the field's length).
+``max_length``
+    If the field is some sort of text field, then the ``max_length`` option can be
+    guessed from the validation constraints (if ``Length`` or ``Range`` is used) or
+    from the Doctrine metadata (via the field's length).
 
 .. note::
 
@@ -771,12 +773,13 @@ of code. Of course, you'll usually need much more flexibility when rendering:
 You already know the ``form_start()`` and ``form_end()`` functions, but what do
 the other functions do?
 
-* ``form_errors(form)`` - Renders any errors global to the whole form
-  (field-specific errors are displayed next to each field);
+``form_errors(form)``
+    Renders any errors global to the whole form (field-specific errors are displayed
+    next to each field).
 
-* ``form_row(form.dueDate)`` - Renders the label, any errors, and the HTML
-  form widget for the given field (e.g. ``dueDate``) inside, by default, a
-  ``div`` element.
+``form_row(form.dueDate)``
+    Renders the label, any errors, and the HTML form widget for the given field
+    (e.g. ``dueDate``) inside, by default, a ``div`` element.
 
 The majority of the work is done by the ``form_row`` helper, which renders
 the label, errors and HTML form widget of each field inside a ``div`` tag by

book/http_cache.rst

@@ -202,34 +202,39 @@ method::
 
 Here is a list of the main options:
 
-* ``default_ttl``: The number of seconds that a cache entry should be
-  considered fresh when no explicit freshness information is provided in a
-  response. Explicit ``Cache-Control`` or ``Expires`` headers override this
-  value (default: ``0``);
-
-* ``private_headers``: Set of request headers that trigger "private"
-  ``Cache-Control`` behavior on responses that don't explicitly state whether
-  the response is ``public`` or ``private`` via a ``Cache-Control`` directive.
-  (default: ``Authorization`` and ``Cookie``);
-
-* ``allow_reload``: Specifies whether the client can force a cache reload by
-  including a ``Cache-Control`` "no-cache" directive in the request. Set it to
-  ``true`` for compliance with RFC 2616 (default: ``false``);
-
-* ``allow_revalidate``: Specifies whether the client can force a cache
-  revalidate by including a ``Cache-Control`` "max-age=0" directive in the
-  request. Set it to ``true`` for compliance with RFC 2616 (default: false);
-
-* ``stale_while_revalidate``: Specifies the default number of seconds (the
-  granularity is the second as the Response TTL precision is a second) during
-  which the cache can immediately return a stale response while it revalidates
-  it in the background (default: ``2``); this setting is overridden by the
-  ``stale-while-revalidate`` HTTP ``Cache-Control`` extension (see RFC 5861);
-
-* ``stale_if_error``: Specifies the default number of seconds (the granularity
-  is the second) during which the cache can serve a stale response when an
-  error is encountered (default: ``60``). This setting is overridden by the
-  ``stale-if-error`` HTTP ``Cache-Control`` extension (see RFC 5861).
+``default_ttl``
+    The number of seconds that a cache entry should be considered fresh when no
+    explicit freshness information is provided in a response. Explicit
+    ``Cache-Control`` or ``Expires`` headers override this value (default: ``0``).
+
+``private_headers``
+    Set of request headers that trigger "private" ``Cache-Control`` behavior on
+    responses that don't explicitly state whether the response is ``public`` or
+    ``private`` via a ``Cache-Control`` directive (default: ``Authorization``
+    and ``Cookie``).
+
+``allow_reload``
+    Specifies whether the client can force a cache reload by including a
+    ``Cache-Control`` "no-cache" directive in the request. Set it to ``true`` for
+    compliance with RFC 2616 (default: ``false``).
+
+``allow_revalidate``
+    Specifies whether the client can force a cache revalidate by including a
+    ``Cache-Control`` "max-age=0" directive in the request. Set it to ``true`` for
+    compliance with RFC 2616 (default: false).
+
+``stale_while_revalidate``
+    Specifies the default number of seconds (the granularity is the second as the
+    Response TTL precision is a second) during which the cache can immediately
+    return a stale response while it revalidates it in the background (default:
+    ``2``); this setting is overridden by the ``stale-while-revalidate`` HTTP
+    ``Cache-Control`` extension (see RFC 5861).
+
+``stale_if_error``
+    Specifies the default number of seconds (the granularity is the second) during
+    which the cache can serve a stale response when an error is encountered
+    (default: ``60``). This setting is overridden by the ``stale-if-error`` HTTP
+    ``Cache-Control`` extension (see RFC 5861).
 
 If ``debug`` is ``true``, Symfony automatically adds a ``X-Symfony-Cache``
 header to the response containing useful information about cache hits and
@@ -339,11 +344,12 @@ and then returned to every subsequent user who asked for their account page!
 
 To handle this situation, every response may be set to be public or private:
 
-* *public*: Indicates that the response may be cached by both private and
-  shared caches;
+*public*
+    Indicates that the response may be cached by both private and shared caches.
 
-* *private*: Indicates that all or part of the response message is intended
-  for a single user and must not be cached by a shared cache.
+*private*
+    Indicates that all or part of the response message is intended for a single
+    user and must not be cached by a shared cache.
 
 Symfony conservatively defaults each response to be private. To take advantage
 of shared caches (like the Symfony reverse proxy), the response will need
@@ -1033,12 +1039,14 @@ possible.
 
 The ``render_esi`` helper supports two other useful options:
 
-* ``alt``: used as the ``alt`` attribute on the ESI tag, which allows you
-  to specify an alternative URL to be used if the ``src`` cannot be found;
+``alt``
+    Used as the ``alt`` attribute on the ESI tag, which allows you to specify an
+    alternative URL to be used if the ``src`` cannot be found.
 
-* ``ignore_errors``: if set to true, an ``onerror`` attribute will be added
-  to the ESI with a value of ``continue`` indicating that, in the event of
-  a failure, the gateway cache will simply remove the ESI tag silently.
+``ignore_errors``
+    If set to true, an ``onerror`` attribute will be added to the ESI with a value
+    of ``continue`` indicating that, in the event of a failure, the gateway cache
+    will simply remove the ESI tag silently.
 
 .. index::
     single: Cache; Invalidation

book/http_fundamentals.rst

@@ -518,30 +518,32 @@ libraries that can be used inside *any* PHP project. These libraries, called
 the *Symfony Components*, contain something useful for almost any situation,
 regardless of how your project is developed. To name a few:
 
-* :doc:`HttpFoundation </components/http_foundation/introduction>` - Contains
-  the ``Request`` and ``Response`` classes, as well as other classes for handling
-  sessions and file uploads;
+:doc:`HttpFoundation </components/http_foundation/introduction>`
+    Contains the ``Request`` and ``Response`` classes, as well as other classes for
+    handling sessions and file uploads.
 
-* :doc:`Routing </components/routing/introduction>` - Powerful and fast routing system that
-  allows you to map a specific URI (e.g. ``/contact``) to some information
-  about how that request should be handled (e.g. execute the ``contactAction()``
-  method);
+:doc:`Routing </components/routing/introduction>`
+    Powerful and fast routing system that allows you to map a specific URI
+    (e.g. ``/contact``) to some information about how that request should be handled
+    (e.g. execute the ``contactAction()`` method).
 
-* :doc:`Form </components/form/introduction>` - A full-featured and flexible
-  framework for creating forms and handling form submissions;
+:doc:`Form </components/form/introduction>`
+    A full-featured and flexible framework for creating forms and handling form
+    submissions.
 
-* `Validator`_ - A system for creating rules about data and then validating
-  whether or not user-submitted data follows those rules;
+`Validator`_
+    A system for creating rules about data and then validating whether or not
+    user-submitted data follows those rules.
 
-* :doc:`Templating </components/templating/introduction>` - A toolkit for rendering
-  templates, handling template inheritance (i.e. a template is decorated with
-  a layout) and performing other common template tasks;
+:doc:`Templating </components/templating/introduction>`
+    A toolkit for rendering templates, handling template inheritance (i.e. a
+    template is decorated with a layout) and performing other common template tasks.
 
-* :doc:`Security </components/security/introduction>` - A powerful library for
-  handling all types of security inside an application;
+:doc:`Security </components/security/introduction>`
+    A powerful library for handling all types of security inside an application.
 
-* :doc:`Translation </components/translation/introduction>` - A framework for
-  translating strings in your application.
+:doc:`Translation </components/translation/introduction>`
+    A framework for translating strings in your application.
 
 Each and every one of these components is decoupled and can be used in *any*
 PHP project, regardless of whether or not you use the Symfony framework.