Merge branch '2.3' into 2.6

* 2.3:
  Adding one more note about why we're in config.yml
  [#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
  Applied comments
  [BestPractices] restructured text format for the installation instructions template
  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
  Making the channel handler more useful by showing it on the prod environment

Author: weaverryan

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:
 

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'
 }

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

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.)

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

cookbook/logging/channels_handlers.rst

@@ -4,21 +4,29 @@
 How to Log Messages to different Files
 ======================================
 
-The Symfony Standard Edition contains a bunch of channels for logging: ``doctrine``,
-``event``, ``security`` and ``request``. Each channel corresponds to a logger
-service (``monolog.logger.XXX``) in the container and is injected to the
-concerned service. The purpose of channels is to be able to organize different
-types of log messages.
+The Symfony Framework organizes log messages into channels. By default, there
+are several channels, including ``doctrine``, ``event``, ``security``, ``request``
+and more. The channel is printed in the log message and can also be used
+to direct different channels to different places/files.
 
 By default, Symfony logs every message into a single file (regardless of
 the channel).
 
+.. note::
+
+    Each channel corresponds to a logger service (``monolog.logger.XXX``)
+    in the container (use the ``container:debug`` command to see a full list)
+    and those are injected into different services.
+
+.. _logging-channel-handler:
+
 Switching a Channel to a different Handler
 ------------------------------------------
 
-Now, suppose you want to log the ``doctrine`` channel to a different file.
-
-To do so, just create a new handler and configure it like this:
+Now, suppose you want to log the ``security`` channel to a different file.
+To do this, just create a new handler and configure it to log only messages
+from the ``security`` channel. You might add this in ``config.yml`` to log
+in all environments, or just ``config_prod.yml`` to happen only in ``prod``:
 
 .. configuration-block::
 
@@ -27,14 +35,17 @@ To do so, just create a new handler and configure it like this:
         # app/config/config.yml
         monolog:
             handlers:
-                main:
-                    type:     stream
-                    path:     /var/log/symfony.log
-                    channels: ["!doctrine"]
-                doctrine:
+                security:
+                    # log all messages (since debug is the lowest level)
+                    level:    debug
                     type:     stream
-                    path:     /var/log/doctrine.log
-                    channels: [doctrine]
+                    path:     "%kernel.logs_dir%/security.log"
+                    channels: [security]
+
+                # an example of *not* logging security channel messages for this handler
+                main:
+                    # ...
+                    # channels: ["!security"]
 
     .. code-block:: xml
 
@@ -48,15 +59,16 @@ To do so, just create a new handler and configure it like this:
                 http://symfony.com/schema/dic/monolog/monolog-1.0.xsd"
         >
             <monolog:config>
-                <monolog:handler name="main" type="stream" path="/var/log/symfony.log">
+                <monolog:handler name="security" type="stream" path="%kernel.logs_dir%/security.log">
                     <monolog:channels>
-                        <monolog:channel>!doctrine</monolog:channel>
+                        <monolog:channel>security</monolog:channel>
                     </monolog:channels>
                 </monolog:handler>
 
-                <monolog:handler name="doctrine" type="stream" path="/var/log/doctrine.log">
+                <monolog:handler name="main" type="stream" path="%kernel.logs_dir%/main.log">
+                    <!-- ... -->
                     <monolog:channels>
-                        <monolog:channel>doctrine</monolog:channel>
+                        <monolog:channel>!security</monolog:channel>
                     </monolog:channels>
                 </monolog:handler>
             </monolog:config>
@@ -67,18 +79,17 @@ To do so, just create a new handler and configure it like this:
         // app/config/config.php
         $container->loadFromExtension('monolog', array(
             'handlers' => array(
-                'main'     => array(
+                'security' => array(
                     'type'     => 'stream',
-                    'path'     => '/var/log/symfony.log',
+                    'path'     => '%kernel.logs_dir%/security.log',
                     'channels' => array(
-                        '!doctrine',
+                        'security',
                     ),
                 ),
-                'doctrine' => array(
-                    'type'     => 'stream',
-                    'path'     => '/var/log/doctrine.log',
+                'main'     => array(
+                    // ...
                     'channels' => array(
-                        'doctrine',
+                        '!security',
                     ),
                 ),
             ),