Merge branch '2.8' into 3.1

* 2.8:
  [#6961] add additional config formats
  [#7104] minor typo fix
  Fixed minor syntax issues and typos
  more precision on class name, and lazy service
  add warning about the limitation on using swiftmail with file spool and lazy loading
  Removed the proposed note and updated the title
  Added note on ODM id notation being different
  [#7099] remove trailing whitespaces
  Clarify Process::wait() callback behaviour
  Minor text fix - wrong submit button label (Forms)
  [Doctrine] Slave/Master configuration options
  Fix broken link
  Fix typo
  Add missing parenthesis for methods and a few minor tweaks
  [Doctrine] Exception note about functions with named managers

Author: xabbuh

components/process.rst

@@ -133,6 +133,23 @@ are done doing other stuff::
 
     // ... do other things
 
+    $process->wait();
+
+    // ... do things after the process has finished
+
+.. note::
+
+    The :method:`Symfony\\Component\\Process\\Process::wait` method is blocking,
+    which means that your code will halt at this line until the external
+    process is completed.
+
+:method:`Symfony\\Component\\Process\\Process::wait` takes one optional argument:
+a callback that is called repeatedly whilst the process is still running, passing
+in the output and its type::
+
+    $process = new Process('ls -lsa');
+    $process->start();
+
     $process->wait(function ($type, $buffer) {
         if (Process::ERR === $type) {
             echo 'ERR > '.$buffer;
@@ -141,12 +158,6 @@ are done doing other stuff::
         }
     });
 
-.. note::
-
-    The :method:`Symfony\\Component\\Process\\Process::wait` method is blocking,
-    which means that your code will halt at this line until the external
-    process is completed.
-
 Streaming to the Standard Input of a Process
 --------------------------------------------
 

deployment/platformsh.rst

@@ -185,7 +185,7 @@ That's it! Your Symfony application will be bootstrapped and deployed. You'll
 soon be able to see it in your browser.
 
 .. _`Platform.sh`: https://platform.sh
-.. _`Platform.sh documentation`: https://docs.platform.sh/toolstacks/symfony/symfony-getting-started
+.. _`Platform.sh documentation`: https://docs.platform.sh/frameworks/symfony.html
 .. _`Platform.sh project`: https://marketplace.commerceguys.com/platform/buy-now
 .. _`Platform.sh configuration files`: https://docs.platform.sh/reference/configuration-files
 .. _`GitHub`: https://github.com/platformsh/platformsh-examples

doctrine.rst

@@ -1,8 +1,8 @@
 .. index::
    single: Doctrine
 
-Databases and Doctrine
-======================
+Databases and the Doctrine ORM
+==============================
 
 One of the most common and challenging tasks for any application
 involves persisting and reading information to and from a database. Although
@@ -582,10 +582,10 @@ Take a look at the previous example in more detail:
   responsible for the process of persisting objects to, and fetching objects
   from, the database.
 
-* **line 17** The ``persist($product)`` call tells Doctrine to "manage" the
+* **line 18** The ``persist($product)`` call tells Doctrine to "manage" the
   ``$product`` object. This does **not** cause a query to be made to the database.
 
-* **line 18** When the ``flush()`` method is called, Doctrine looks through
+* **line 21** When the ``flush()`` method is called, Doctrine looks through
   all of the objects that it's managing to see if they need to be persisted
   to the database. In this example, the ``$product`` object's data doesn't
   exist in the database, so the entity manager executes an ``INSERT`` query,
@@ -675,7 +675,7 @@ Once you have a repository object, you can access all sorts of helpful methods::
     Of course, you can also issue complex queries, which you'll learn more
     about in the :ref:`doctrine-queries` section.
 
-You can also take advantage of the useful ``findBy`` and ``findOneBy`` methods
+You can also take advantage of the useful ``findBy()`` and ``findOneBy()`` methods
 to easily fetch objects based on multiple conditions::
 
     $repository = $this->getDoctrine()->getRepository('AppBundle:Product');
@@ -734,7 +734,7 @@ Updating an object involves just three steps:
 
 #. fetching the object from Doctrine;
 #. modifying the object;
-#. calling ``flush()`` on the entity manager
+#. calling ``flush()`` on the entity manager.
 
 Notice that calling ``$em->persist($product)`` isn't necessary. Recall that
 this method simply tells Doctrine to manage or "watch" the ``$product`` object.
@@ -825,7 +825,7 @@ DQL as you start to concatenate strings::
     $repository = $this->getDoctrine()
         ->getRepository('AppBundle:Product');
 
-    // createQueryBuilder automatically selects FROM AppBundle:Product
+    // createQueryBuilder() automatically selects FROM AppBundle:Product
     // and aliases it to "p"
     $query = $repository->createQueryBuilder('p')
         ->where('p.price > :price')

doctrine/custom_dql_functions.rst

@@ -69,4 +69,74 @@ In Symfony, you can register your custom DQL functions as follows:
             ),
         ));
 
+.. note::
+
+    In case the ``entity_managers`` were named explicitly, configuring the functions with the
+    orm directly will trigger the exception `Unrecognized option "dql" under "doctrine.orm"`.
+    The `dql` configuration block must be defined under the named entity manager.
+
+    .. configuration-block::
+
+	.. code-block:: yaml
+
+	    # app/config/config.yml
+	    doctrine:
+		orm:
+		    # ...
+		    entity_managers:
+			example_manager:
+			    # Place your functions here
+			    dql:
+				datetime_functions:
+				    test_datetime: AppBundle\DQL\DatetimeFunction
+
+        .. code-block:: xml
+
+            # app/config/config.xml
+            <?xml version="1.0" encoding="UTF-8" ?>
+            <container xmlns="http://symfony.com/schema/dic/services"
+                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    http://symfony.com/schema/dic/services/services-1.0.xsd
+                    http://symfony.com/schema/dic/doctrine
+                    http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
+
+                <doctrine:config>
+                    <doctrine:orm>
+                        <!-- ... -->
+
+                        <doctrine:entity-manager name="example_manager">
+                            <!-- place your functions here -->
+                            <doctrine:dql>
+                                <doctrine:datetime-function name="test_datetime">
+                                    AppBundle\DQL\DatetimeFunction
+                                </doctrine:datetime-function>
+                            </doctrine:dql>
+                        </doctrine:entity-manager>
+                    </doctrine:orm>
+                </doctrine:config>
+            </container>
+
+        .. code-block:: php
+
+            // app/config/config.php
+            $container->loadFromExtension('doctrine', array(
+                'doctrine' => array(
+                    'orm' => array(
+                        // ...
+                        'entity_managers' => array(
+                            'example_manager' => array(
+                                // place your functions here
+                                'dql' => array(
+                                    'datetime_functions' => array(
+                                        'test_datetime' => 'AppBundle\DQL\DatetimeFunction',
+                                    ),
+                                ),
+                            ),
+                        ),
+                    ),
+                ),
+            ));
+
 .. _`DQL User Defined Functions`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/cookbook/dql-user-defined-functions.html

email/spool.rst

@@ -141,3 +141,21 @@ You can also set the time limit in seconds:
 Of course you will not want to run this manually in reality. Instead, the
 console command should be triggered by a cron job or scheduled task and run
 at a regular interval.
+
+.. caution::
+
+    When you create a message with SwiftMailer, it generates a ``Swift_Message``
+    class. If the ``swiftmailer`` service is lazy loaded, it generates instead a
+    proxy class named ``Swift_Message_<someRandomCharacters>``.
+
+    If you use the memory spool, this change is transparent and has no impact.
+    But when using the filesystem spool, the message class is serialized in
+    a file with the randomized class name. The problem is that this random 
+    class name changes on every cache clear. So if you send a mail and then you
+    clear the cache, the message will not be unserializable.
+
+    On the next execution of ``swiftmailer:spool:send`` an error will raise because
+    the class ``Swift_Message_<someRandomCharacters>`` doesn't exist (anymore).
+
+    The solutions are either to use the memory spool or to load the 
+    ``swiftmailer`` service without the ``lazy`` option (see :doc:`/service_container/lazy_services`).

forms.rst

@@ -96,7 +96,7 @@ from inside a controller::
             $form = $this->createFormBuilder($task)
                 ->add('task', TextType::class)
                 ->add('dueDate', DateType::class)
-                ->add('save', SubmitType::class, array('label' => 'Create Task'))
+                ->add('save', SubmitType::class, array('label' => 'Create Post'))
                 ->getForm();
 
             return $this->render('default/new.html.twig', array(

quick_tour/the_big_picture.rst

@@ -114,7 +114,7 @@ start with ``/**``, whereas regular PHP comments start with ``/*``.
 
 The first value of ``@Route()`` defines the URL that will trigger the execution
 of the action. As you don't have to add the host of your application to
-the URL (e.g. ```http://example.com``), these URLs are always relative and
+the URL (e.g. ``http://example.com``), these URLs are always relative and
 they are usually called *paths*. In this case, the ``/`` path refers to the
 application homepage. The second value of ``@Route()`` (e.g. ``name="homepage"``)
 is optional and sets the name of this route. For now this name is not needed,

reference/configuration/doctrine.rst

@@ -68,6 +68,8 @@ Full Default Configuration
                         profiling:            '%kernel.debug%'
                         driver_class:         ~
                         wrapper_class:        ~
+                        # the DBAL keepSlave option
+                        keep_slave:           false
                         options:
                             # an array of options
                             key:                  []
@@ -209,6 +211,7 @@ Full Default Configuration
                         logging="%kernel.debug%"
                         platform-service="MyOwnDatabasePlatformService"
                         server-version="5.6"
+                        keep-slave="false"
                     >
                         <doctrine:option key="foo">bar</doctrine:option>
                         <doctrine:mapping-type name="enum">string</doctrine:mapping-type>
@@ -405,8 +408,6 @@ The following block shows all possible configuration keys:
                     enum: string
                 types:
                     custom: Acme\HelloBundle\MyCustomType
-                # the DBAL keepSlave option
-                keep_slave:           false
 
     .. code-block:: xml