Merge branch '2.8'

* 2.8: (21 commits)
  Adding one more note about why we're in config.yml
  [symfony#5302] Re-reading sections after moving them, and tweaking some things that did not make sense anymore
  Update doctrine.rst
  Place DQL in front of QueryBuilder
  Slight re-wording of new paragraph with the goal of being as short as possible
  Fix formatting error
  Created a new section for rotating log files and explained the max_files configuration option
  Fixes after review
  [VarDumper] Add doc for assertDump* assertions
  Changed comment from # to //
  Applied comments
  [BestPractices] restructured text format for the installation instructions template
  Better illustrate what the "user mistake" is.
  Fix typo
  Added new recipe on upgrading a major version
  Fix little title case mistake
  Created 'upgrade' cookbook section
  Added XML and PHP configuration samples
  Added a note about the rotating_file monolog handler
  Changing back to config.yml and fixing some code block mistakes thanks to Wouter
  ...

Author: weaverryan

Diff for: book/doctrine.rst

@@ -722,27 +722,30 @@ instead of querying for rows on a table (e.g. ``product``).
 When querying in Doctrine, you have two options: writing pure Doctrine queries
 or using Doctrine's Query Builder.
 
-Querying for Objects Using Doctrine's Query Builder
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Querying for Objects with DQL
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Imagine that you want to query for products, but only return products that
 cost more than ``19.99``, ordered from cheapest to most expensive. You can use
-Doctrine's ``QueryBuilder`` for this::
+Doctrine's native SQL-like language called DQL to make a query for this::
 
-    $repository = $this->getDoctrine()
-        ->getRepository('AppBundle:Product');
-
-    $query = $repository->createQueryBuilder('p')
-        ->where('p.price > :price')
-        ->setParameter('price', '19.99')
-        ->orderBy('p.price', 'ASC')
-        ->getQuery();
+    $em = $this->getDoctrine()->getManager();
+    $query = $em->createQuery(
+        'SELECT p
+        FROM AppBundle:Product p
+        WHERE p.price > :price
+        ORDER BY p.price ASC'
+    )->setParameter('price', '19.99');
 
     $products = $query->getResult();
+    // to get just one result:
+    // $product = $query->setMaxResults(1)->getOneOrNullResult();
 
-The ``QueryBuilder`` object contains every method necessary to build your
-query. By calling the ``getQuery()`` method, the query builder returns a
-normal ``Query`` object, which can be used to get the result of the query.
+If you're comfortable with SQL, then DQL should feel very natural. The biggest
+difference is that you need to think in terms of "objects" instead of rows
+in a database. For this reason, you select *from* the ``AppBundle:Product``
+*object* (an optional shortcut for ``AppBundle\Entity\Product``) and then
+alias it as ``p``.
 
 .. tip::
 
@@ -751,40 +754,42 @@ normal ``Query`` object, which can be used to get the result of the query.
     (``:price`` in the example above) as it prevents SQL injection attacks.
 
 The ``getResult()`` method returns an array of results. To get only one
-result, you can use ``getSingleResult()`` (which throws an exception if there
-is no result) or ``getOneOrNullResult()``::
+result, you can use ``getOneOrNullResult()``::
 
-    $product = $query->getOneOrNullResult();
+    $product = $query->setMaxResults(1)->getOneOrNullResult();
 
-For more information on Doctrine's Query Builder, consult Doctrine's
-`Query Builder`_ documentation.
+The DQL syntax is incredibly powerful, allowing you to easily join between
+entities (the topic of :ref:`relations <book-doctrine-relations>` will be
+covered later), group, etc. For more information, see the official
+`Doctrine Query Language`_ documentation.
 
-Querying for Objects with DQL
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Querying for Objects Using Doctrine's Query Builder
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Instead of using the ``QueryBuilder``, you can alternatively write the queries
-directly using DQL::
+Instead of writing a DQL string, you can alternatively use a helpful object called
+the ``QueryBuilder`` to build that string for you::
 
-    $em = $this->getDoctrine()->getManager();
-    $query = $em->createQuery(
-        'SELECT p
-        FROM AppBundle:Product p
-        WHERE p.price > :price
-        ORDER BY p.price ASC'
-    )->setParameter('price', '19.99');
+    $repository = $this->getDoctrine()
+        ->getRepository('AppBundle:Product');
+
+    // createQueryBuilder automatically selects FROM AppBundle:Product
+    // and aliases it to "p"
+    $query = $repository->createQueryBuilder('p')
+        ->where('p.price > :price')
+        ->setParameter('price', '19.99')
+        ->orderBy('p.price', 'ASC')
+        ->getQuery();
 
     $products = $query->getResult();
+    // to get just one result:
+    // $product = $query->setMaxResults(1)->getOneOrNullResult();
 
-If you're comfortable with SQL, then DQL should feel very natural. The biggest
-difference is that you need to think in terms of "objects" instead of rows
-in a database. For this reason, you select *from* the ``AppBundle:Product``
-*object* and then alias it as ``p`` (as you see, this is equal to what you
-already did in the previous section).
+The ``QueryBuilder`` object contains every method necessary to build your
+query. By calling the ``getQuery()`` method, the query builder returns a
+normal ``Query`` object, which can be used to get the result of the query.
 
-The DQL syntax is incredibly powerful, allowing you to easily join between
-entities (the topic of :ref:`relations <book-doctrine-relations>` will be
-covered later), group, etc. For more information, see the official
-`Doctrine Query Language`_ documentation.
+For more information on Doctrine's Query Builder, consult Doctrine's
+`Query Builder`_ documentation.
 
 .. _book-doctrine-custom-repository-classes:
 

Diff for: components/options_resolver.rst

@@ -96,7 +96,7 @@ the ``Mailer`` class makes a mistake?
 .. code-block:: php
 
     $mailer = new Mailer(array(
-        'usernme' => 'johndoe',
+        'usernme' => 'johndoe',  // usernAme misspelled 
     ));
 
 No error will be shown. In the best case, the bug will appear during testing,

Diff for: components/var_dumper/introduction.rst

@@ -122,6 +122,53 @@ original value. You can configure the limits in terms of:
             <config max-items="250" max-string-length="-1" />
         </container>
 
+Using the VarDumper Component in your PHPUnit Test Suite
+--------------------------------------------------------
+
+.. versionadded:: 2.7
+    The :class:`Symfony\\Component\\VarDumper\\Test\\VarDumperTestTrait` was
+    introduced in Symfony 2.7.
+
+The VarDumper component provides
+:class:`a trait <Symfony\\Component\\VarDumper\\Test\\VarDumperTestTrait>`
+that can help writing some of your tests for PHPUnit.
+
+This will provide you with two new assertions:
+
+:method:`Symfony\\Component\\VarDumper\\Test\\VarDumperTestTrait::assertDumpEquals`
+    verifies that the dump of the variable given as the second argument matches
+    the expected dump provided as a string in the first argument.
+
+:method:`Symfony\\Component\\VarDumper\\Test\\VarDumperTestTrait::assertDumpMatchesFormat`
+    is like the previous method but accepts placeholders in the expected dump,
+    based on the ``assertStringMatchesFormat`` method provided by PHPUnit.
+
+Example::
+
+    class ExampleTest extends \PHPUnit_Framework_TestCase
+    {
+        use \Symfony\Component\VarDumper\Test\VarDumperTestTrait;
+
+        public function testWithDumpEquals()
+        {
+            $testedVar = array(123, 'foo');
+
+            $expectedDump = <<<EOTXT
+    array:2 [
+      0 => 123
+      1 => "foo"
+    ]
+    EOTXT;
+
+            $this->assertDumpEquals($expectedDump, $testedVar);
+        }
+    }
+
+.. tip::
+
+    If you still use PHP 5.3, you can extend the
+    :class:`Symfony\\Component\\VarDumper\\Test\\VarDumperTestClass` instead.
+
 Dump Examples and Output
 ------------------------
 

Diff for: conf.py

@@ -23,6 +23,8 @@
 # adding PhpLexer
 from sphinx.highlighting import lexers
 from pygments.lexers.compiled import CLexer
+from pygments.lexers.special import TextLexer
+from pygments.lexers.text import RstLexer
 from pygments.lexers.web import PhpLexer
 
 # -- General configuration -----------------------------------------------------
@@ -97,14 +99,18 @@
 # -- Settings for symfony doc extension ---------------------------------------------------
 
 # enable highlighting for PHP code not between ``<?php ... ?>`` by default
+lexers['markdown'] = TextLexer()
 lexers['php'] = PhpLexer(startinline=True)
 lexers['php-annotations'] = PhpLexer(startinline=True)
 lexers['php-standalone'] = PhpLexer(startinline=True)
 lexers['php-symfony'] = PhpLexer(startinline=True)
+lexers['rst'] = RstLexer()
 lexers['varnish3'] = CLexer()
 lexers['varnish4'] = CLexer()
 
 config_block = {
+    'markdown': 'Markdown',
+    'rst': 'reStructuredText',
     'varnish3': 'Varnish 3',
     'varnish4': 'Varnish 4'
 }

Diff for: contributing/code/bc.rst

@@ -1,4 +1,4 @@
-Our backwards Compatibility Promise
+Our Backwards Compatibility Promise
 ===================================
 
 Ensuring smooth upgrades of your projects is our first priority. That's why

Diff for: cookbook/bundles/best_practices.rst

@@ -209,52 +209,102 @@ Installation Instructions
 In order to ease the installation of third-party bundles, consider using the
 following standardized instructions in your ``README.md`` file.
 
-.. code-block:: text
+.. configuration-block::
 
-    Installation
-    ============
+    .. code-block:: markdown
 
-    Step 1: Download the Bundle
-    ---------------------------
+        Installation
+        ============
 
-    Open a command console, enter your project directory and execute the
-    following command to download the latest stable version of this bundle:
+        Step 1: Download the Bundle
+        ---------------------------
 
-    ```bash
-    $ composer require <package-name> "~1"
-    ```
+        Open a command console, enter your project directory and execute the
+        following command to download the latest stable version of this bundle:
 
-    This command requires you to have Composer installed globally, as explained
-    in the [installation chapter](https://getcomposer.org/doc/00-intro.md)
-    of the Composer documentation.
+        ```bash
+        $ composer require <package-name> "~1"
+        ```
 
-    Step 2: Enable the Bundle
-    -------------------------
+        This command requires you to have Composer installed globally, as explained
+        in the [installation chapter](https://getcomposer.org/doc/00-intro.md)
+        of the Composer documentation.
 
-    Then, enable the bundle by adding the following line in the `app/AppKernel.php`
-    file of your project:
+        Step 2: Enable the Bundle
+        -------------------------
 
-    ```php
-    <?php
-    // app/AppKernel.php
+        Then, enable the bundle by adding the following line in the `app/AppKernel.php`
+        file of your project:
 
-    // ...
-    class AppKernel extends Kernel
-    {
-        public function registerBundles()
+        ```php
+        <?php
+        // app/AppKernel.php
+
+        // ...
+        class AppKernel extends Kernel
         {
-            $bundles = array(
-                // ...
+            public function registerBundles()
+            {
+                $bundles = array(
+                    // ...
+
+                    new <vendor>\<bundle-name>\<bundle-long-name>(),
+                );
 
-                new <vendor>\<bundle-name>\<bundle-long-name>(),
-            );
+                // ...
+            }
 
             // ...
         }
+        ```
 
-        // ...
-    }
-    ```
+    .. code-block:: rst
+
+        Installation
+        ============
+
+        Step 1: Download the Bundle
+        ---------------------------
+
+        Open a command console, enter your project directory and execute the
+        following command to download the latest stable version of this bundle:
+
+        .. code-block:: bash
+
+            $ composer require <package-name> "~1"
+
+        This command requires you to have Composer installed globally, as explained
+        in the `installation chapter`_ of the Composer documentation.
+
+        Step 2: Enable the Bundle
+        -------------------------
+
+        Then, enable the bundle by adding the following line in the ``app/AppKernel.php``
+        file of your project:
+
+        .. code-block:: php
+
+            <?php
+            // app/AppKernel.php
+
+            // ...
+            class AppKernel extends Kernel
+            {
+                public function registerBundles()
+                {
+                    $bundles = array(
+                        // ...
+
+                        new <vendor>\<bundle-name>\<bundle-long-name>(),
+                    );
+
+                    // ...
+                }
+
+                // ...
+            }
+
+        .. _`installation chapter`: https://getcomposer.org/doc/00-intro.md
 
 This template assumes that your bundle is in its ``1.x`` version. If not, change
 the ``"~1"`` installation version accordingly (``"~2"``, ``"~3"``, etc.)

Diff for: cookbook/index.rst

@@ -30,7 +30,7 @@ The Cookbook
     symfony1
     templating/index
     testing/index
-    upgrading
+    upgrade/index
     validation/index
     web_server/index
     web_services/index