Merge branch '2.3' into 2.6

* 2.3: (30 commits)
  [#5064] Minor language tweaks
  Switched the first example to a static constructor method
  added some more components for Tobion as a merger
  Fixed variable name in : Reference -> validation constraints -> count -> basic usage -> PHP
  [#5036] Typo fix (probably mine originally) caught by xabbuh
  reword to serves
  Adding a link to define "lts"
  Better wording
  Minor improvement for symfony-installer with LTS
  link to deciders' GitHub profiles
  Add missing use statement in Building Login Form doc Also removed use statement for Route as it is only needed when using annotations for routing
  Fixed incorrect plural form
  Improved the URL of the English reference dictionary
  Reworded the paragraph about enforcing an English reference
  enclose data type with double backticks
  Rewords, tweaks and fixes
  Updated documentation standards (code examples and English use)
  Added double backticks. And also a full stop.
  added link target/label in the cookbook
  Changed link into ref
  ...

Conflicts:
	components/config/definition.rst
	contributing/code/core_team.rst
	cookbook/security/form_login_setup.rst

Author: weaverryan

book/installation.rst

@@ -98,6 +98,17 @@ number as the second argument of the ``new`` command:
     # Windows
     c:\projects\> php symfony.phar new my_project_name 2.3.23
 
+If you want your project to be based on the latest :ref:`Symfony LTS version <releases-lts>`,
+pass ``lts`` as the second argument of the ``new`` command:
+
+.. code-block:: bash
+
+    # Linux, Mac OS X
+    $ symfony new my_project_name lts
+
+    # Windows
+    c:\projects\> php symfony.phar new my_project_name lts
+
 Read the :doc:`Symfony Release process </contributing/community/releases>`
 to better understand why there are several Symfony versions and which one
 to use for your projects.

book/testing.rst

@@ -394,7 +394,7 @@ or perform more complex requests. Some useful examples::
         array('photo' => $photo)
     );
 
-    // Perform a DELETE requests and pass HTTP headers
+    // Perform a DELETE request and pass HTTP headers
     $client->request(
         'DELETE',
         '/post/12',

components/config/definition.rst

@@ -95,13 +95,13 @@ Node Type
 ~~~~~~~~~
 
 It is possible to validate the type of a provided value by using the appropriate
-node definition. Node type are available for:
+node definition. Node types are available for:
 
-* scalar
+* scalar (generic type that includes booleans, strings, integers, floats and ``null``)
 * boolean
 * integer
 * float
-* enum
+* enum (similar to scalar, but it only allows a finite set of values)
 * array
 * variable (no validation)
 
@@ -288,7 +288,8 @@ All options can be documented using the
 :method:`Symfony\\Component\\Config\\Definition\\Builder\\NodeDefinition::info`
 method.
 
-The info will be printed as a comment when dumping the configuration tree.
+The info will be printed as a comment when dumping the configuration tree with
+the ``config:dump`` command.
 
 .. versionadded:: 2.6
     Since Symfony 2.6, the info will also be added to the exception message

components/config/introduction.rst

@@ -9,13 +9,6 @@ The Config Component
     combine, autofill and validate configuration values of any kind, whatever
     their source may be (YAML, XML, INI files, or for instance a database).
 
-.. caution::
-
-    The ``IniFileLoader`` parses the file contents using the
-    :phpfunction:`parse_ini_file` function, therefore, you can only set
-    parameters to string values. To set parameters to other data types
-    (e.g. boolean, integer, etc), the other loaders are recommended.
-
 Installation
 ------------
 

components/config/resources.rst

@@ -4,6 +4,13 @@
 Loading Resources
 =================
 
+.. caution::
+
+    The ``IniFileLoader`` parses the file contents using the
+    :phpfunction:`parse_ini_file` function. Therefore, you can only set
+    parameters to string values. To set parameters to other data types
+    (e.g. boolean, integer, etc), the other loaders are recommended.
+
 Locating Resources
 ------------------
 

contributing/code/core_team.rst

@@ -37,37 +37,37 @@ Active Core Members
 
 * **Project Leader**:
 
-  * **Fabien Potencier** (:leader:`fabpot`).
+  * **Fabien Potencier** (`fabpot`_).
 
 * **Mergers** (``@symfony/mergers`` on GitHub):
 
-  * **Bernhard Schussek** (:merger:`webmozart`) can merge into the Form_,
+  * **Bernhard Schussek** (`webmozart`_) can merge into the Form_,
     Validator_, Icu_, Intl_, Locale_, OptionsResolver_ and PropertyAccess_
     components;
 
-  * **Tobias Schultze** (:merger:`Tobion`) can merge into the Routing_
-    component;
+  * **Tobias Schultze** (`Tobion`_) can merge into the Routing_,
+    OptionsResolver_ and PropertyAccess_ components;
 
-  * **Romain Neutron** (:merger:`romainneutron`) can merge into the
+  * **Romain Neutron** (`romainneutron`_) can merge into the
     Process_ component;
 
-  * **Nicolas Grekas** (:merger:`nicolas-grekas`) can merge into the Debug_
+  * **Nicolas Grekas** (`nicolas-grekas`_) can merge into the Debug_
     component, the VarDumper_ component and the DebugBundle_;
 
-  * **Christophe Coevoet** (:merger:`stof`) can merge into the BrowserKit_,
+  * **Christophe Coevoet** (`stof`_) can merge into the BrowserKit_,
     Config_, Console_, DependencyInjection_, DomCrawler_, EventDispatcher_,
     HttpFoundation_, HttpKernel_, Serializer_, Stopwatch_, DoctrineBridge_,
     MonologBridge_, and TwigBridge_ components;
 
-  * **Kévin Dunglas** (:merger:`dunglas`) can merge into the Serializer_
+  * **Kévin Dunglas** (`dunglas`_) can merge into the Serializer_
     component.
 
 * **Deciders** (``@symfony/deciders`` on GitHub):
 
-  * **Jakub Zalas** (:decider:`jakzal`);
-  * **Jordi Boggiano** (:decider:`seldaek`);
-  * **Lukas Kahwe Smith** (:decider:`lsmith77`);
-  * **Ryan Weaver** (:decider:`weaverryan`).
+  * **Jakub Zalas** (`jakzal`_);
+  * **Jordi Boggiano** (`seldaek`_);
+  * **Lukas Kahwe Smith** (`lsmith77`_);
+  * **Ryan Weaver** (`weaverryan`_).
 
 Core Membership Application
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -170,3 +170,14 @@ discretion of the **Project Leader**.
 .. _Validator: https://github.com/symfony/Validator
 .. _VarDumper: https://github.com/symfony/var-dumper
 .. _DebugBundle: https://github.com/symfony/debug-bundle
+.. _`fabpot`: https://github.com/fabpot/
+.. _`webmozart`: https://github.com/webmozart/
+.. _`Tobion`: https://github.com/Tobion/
+.. _`romainneutron`: https://github.com/romainneutron/
+.. _`nicolas-grekas`: https://github.com/nicolas-grekas/
+.. _`stof`: https://github.com/stof/
+.. _`dunglas`: https://github.com/dunglas/
+.. _`jakzal`: https://github.com/jakzal/
+.. _`Seldaek`: https://github.com/Seldaek/
+.. _`lsmith77`: https://github.com/lsmith77/
+.. _`weaverryan`: https://github.com/weaverryan/

contributing/community/releases.rst

@@ -60,6 +60,8 @@ Standard Versions
 A standard minor version is maintained for an *eight month* period for bug
 fixes, and for a *fourteen month* period for security issue fixes.
 
+.. _releases-lts:
+
 Long Term Support Versions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 

contributing/documentation/standards.rst

@@ -8,7 +8,8 @@ Sphinx
 ------
 
 * The following characters are chosen for different heading levels: level 1
-  is ``=``, level 2 ``-``, level 3 ``~``, level 4 ``.`` and level 5 ``"``;
+  is ``=`` (equal sign), level 2 ``-`` (dash), level 3 ``~`` (tilde), level 4
+  ``.`` (dot) and level 5 ``"`` (double quote);
 * Each line should break approximately after the first word that crosses the
   72nd character (so most lines end up being 72-78 characters);
 * The ``::`` shorthand is *preferred* over ``.. code-block:: php`` to begin a PHP
@@ -50,6 +51,12 @@ Code Examples
 
 * The code follows the :doc:`Symfony Coding Standards </contributing/code/standards>`
   as well as the `Twig Coding Standards`_;
+* The code examples should look real for a web application context. Avoid abstract
+  or trivial examples (``foo``, ``bar``, ``demo``, etc.);
+* The code should follow the :doc:`Symfony Best Practices </best_practices/introduction>`.
+  Unless the example requires a custom bundle, make sure to always use the
+  ``AppBundle`` bundle to store your code;
+* Use ``Acme`` when the code requires a vendor name;
 * To avoid horizontal scrolling on code blocks, we prefer to break a line
   correctly if it crosses the 85th character;
 * When you fold one or more lines of code, place ``...`` in a comment at the point
@@ -140,8 +147,12 @@ Files and Directories
 English Language Standards
 --------------------------
 
-* **English Dialect**: use the United States English dialect, commonly called
-  `American English`_.
+Symfony documentation uses the United States English dialect, commonly called
+`American English`_. The `American English Oxford Dictionary`_ is used as the
+vocabulary reference.
+
+In addition, documentation follows these rules:
+
 * **Section titles**: use a variant of the title case, where the first
   word is always capitalized and all other words are capitalized, except for
   the closed-class words (read Wikipedia article about `headings and titles`_).
@@ -164,6 +175,7 @@ English Language Standards
 .. _`the Sphinx documentation`: http://sphinx-doc.org/rest.html#source-code
 .. _`Twig Coding Standards`: http://twig.sensiolabs.org/doc/coding_standards.html
 .. _`American English`: http://en.wikipedia.org/wiki/American_English
+.. _`American English Oxford Dictionary`: http://www.oxforddictionaries.com/definition/american_english/
 .. _`headings and titles`: http://en.wikipedia.org/wiki/Letter_case#Headings_and_publication_titles
 .. _`Serial (Oxford) Commas`: http://en.wikipedia.org/wiki/Serial_comma
 .. _`nosism`: http://en.wikipedia.org/wiki/Nosism

cookbook/configuration/web_server_configuration.rst

@@ -21,7 +21,7 @@ to use PHP :ref:`with Nginx <web-server-nginx>`.
     static files, including images, stylesheets and JavaScript files. It is
     also where the front controllers live. For more details, see the :ref:`the-web-directory`.
 
-    The web directory services as the document root when configuring your
+    The web directory serves as the document root when configuring your
     web server. In the examples below, the ``web/`` directory will be the
     document root. This directory is ``/var/www/project/web/``.
 

cookbook/email/dev_environment.rst

@@ -119,6 +119,8 @@ the replaced address, so you can still see who it would have been sent to.
     These are ``X-Swift-Cc`` and ``X-Swift-Bcc`` for the ``CC`` and ``BCC``
     addresses respectively.
 
+.. _sending-to-a-specified-address-but-with-exceptions:
+
 Sending to a Specified Address but with Exceptions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

cookbook/form/unit_testing.rst

@@ -55,8 +55,7 @@ The simplest ``TypeTestCase`` implementation looks like the following::
             $type = new TestedType();
             $form = $this->factory->create($type);
 
-            $object = new TestObject();
-            $object->fromArray($formData);
+            $object = TestObject::fromArray($formData);
 
             // submit the data to the form directly
             $form->submit($formData);

cookbook/security/form_login_setup.rst

@@ -76,31 +76,29 @@ First, enable form login under your firewall:
 Now, when the security system initiates the authentication process, it will
 redirect the user to the login form ``/login``. Implementing this login form
 visually is your job. First, create a new ``SecurityController`` inside a
-bundle with an empty ``loginAction``::
+bundle::
 
     // src/AppBundle/Controller/SecurityController.php
     namespace AppBundle\Controller;
 
-    use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
     use Symfony\Bundle\FrameworkBundle\Controller\Controller;
+    use Symfony\Component\HttpFoundation\Request;
 
     class SecurityController extends Controller
     {
-        public function loginAction(Request $request)
-        {
-            // todo...
-        }
     }
 
-Next, create two routes: one for each of the paths your configured earlier
+Next, create two routes: one for each of the paths you configured earlier
 under your ``form_login`` configuration (``/login`` and ``/login_check``):
 
 .. configuration-block::
 
     .. code-block:: php-annotations
 
         // src/AppBundle/Controller/SecurityController.php
+
         // ...
+        use Symfony\Component\HttpFoundation\Request;
         use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
 
         class SecurityController extends Controller
@@ -110,14 +108,15 @@ under your ``form_login`` configuration (``/login`` and ``/login_check``):
              */
             public function loginAction(Request $request)
             {
-                // todo ...
             }
 
             /**
              * @Route("/login_check", name="login_check")
              */
             public function loginCheckAction()
             {
+                // this controller will not be executed,
+                // as the route is handled by the Security system
             }
         }
 
@@ -129,6 +128,8 @@ under your ``form_login`` configuration (``/login`` and ``/login_check``):
             defaults: { _controller: AppBundle:Security:login }
         login_check:
             path: /login_check
+            # no controller is bound to this route
+            # as it's handled by the Security system
 
     .. code-block:: xml
 
@@ -144,6 +145,8 @@ under your ``form_login`` configuration (``/login`` and ``/login_check``):
             </route>
 
             <route id="login_check" path="/login_check" />
+            <!-- no controller is bound to this route
+                 as it's handled by the Security system -->
         </routes>
 
     ..  code-block:: php
@@ -157,14 +160,15 @@ under your ``form_login`` configuration (``/login`` and ``/login_check``):
             '_controller' => 'AppBundle:Security:login',
         )));
         $collection->add('login_check', new Route('/login_check', array()));
+        // no controller is bound to this route
+        // as it's handled by the Security system
 
         return $collection;
 
 Great! Next, add the logic to ``loginAction`` that will display the login
 form::
 
     // src/AppBundle/Controller/SecurityController.php
-    // ...
 
     public function loginAction(Request $request)
     {

quick_tour/the_controller.rst

@@ -172,8 +172,10 @@ The ``hello`` action will now match URLs like ``/hello/fabien.xml`` or
 like ``/hello/fabien.js``, because the value of the ``_format`` variable doesn't
 meet its requirements.
 
-Redirecting and Forwarding
---------------------------
+.. _redirecting-and-forwarding:
+
+Redirecting
+-----------
 
 If you want to redirect the user to another page, use the ``redirectToRoute()``
 method::
@@ -193,23 +195,6 @@ method::
 The ``redirectToRoute()`` method takes as arguments the route name and an optional
 array of parameters and redirects the user to the URL generated with those arguments.
 
-You can also internally forward the action to another action of the same or
-different controller using the ``forward()`` method::
-
-    // src/AppBundle/Controller/DefaultController.php
-    class DefaultController extends Controller
-    {
-        /**
-         * @Route("/", name="homepage")
-         */
-        public function indexAction()
-        {
-            return $this->forward('AppBundle:Blog:index', array(
-                'name'  => $name
-            );
-        }
-    }
-
 Displaying Error Pages
 ----------------------
 

reference/configuration/swiftmailer.rst

@@ -32,6 +32,7 @@ Configuration
     * `threshold`_
     * `sleep`_
 * `delivery_address`_
+* `delivery_whitelist`_
 * `disable_delivery`_
 * `logging`_
 
@@ -156,6 +157,15 @@ emails sent during development go to a single account.
 This uses ``Swift_Plugins_RedirectingPlugin``. Original recipients are available
 on the ``X-Swift-To``, ``X-Swift-Cc`` and ``X-Swift-Bcc`` headers.
 
+delivery_whitelist
+~~~~~~~~~~~~~~~~~~
+
+**type**: ``array``
+
+Used in combination with ``delivery_address``. If set, emails matching any of these
+patterns will be delivered like normal, instead of being sent to ``delivery_address``.
+For details, see :ref:`the cookbook entry. <sending-to-a-specified-address-but-with-exceptions>`
+
 disable_delivery
 ~~~~~~~~~~~~~~~~
 

reference/constraints/Count.rst

@@ -89,7 +89,7 @@ you might add the following:
 
         class Participant
         {
-            public static function loadValidatorMetadata(ClassMetadata $data)
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('emails', new Assert\Count(array(
                     'min'        => 1,

reference/forms/types/options/data.rst.inc

@@ -1,7 +1,7 @@
 data
 ~~~~
 
-**type**: mixed **default**: Defaults to field of the underlying object (if there is one)
+**type**: ``mixed`` **default**: Defaults to field of the underlying object (if there is one)
 
 When you create a form, each field initially displays the value of the
 corresponding property of the form's domain object (if an object is bound