symfony · greatalf · Apr 8, 2018 · May 31, 2018 · May 23, 2018 · Jun 11, 2018
diff --git a/best_practices/security.rst b/best_practices/security.rst
@@ -121,7 +121,7 @@ Using ``@Security``, this looks like:
      * Displays a form to create a new Post entity.
      *
      * @Route("/new", name="admin_post_new")
-     * @Security("has_role('ROLE_ADMIN')")
+     * @Security("is_granted('ROLE_ADMIN')")
      */
     public function new()
     {

diff --git a/bundles/configuration.rst b/bundles/configuration.rst
@@ -180,10 +180,9 @@ The ``Configuration`` class to handle the sample configuration looks like::
     {
         public function getConfigTreeBuilder()
         {
-            $treeBuilder = new TreeBuilder();
-            $rootNode = $treeBuilder->root('acme_social');
+            $treeBuilder = new TreeBuilder('acme_social');
 
-            $rootNode
+            $treeBuilder->getRootNode()
                 ->children()
                     ->arrayNode('twitter')
                         ->children()
@@ -198,6 +197,9 @@ The ``Configuration`` class to handle the sample configuration looks like::
         }
     }
 
+.. versionadded:: 4.2
+    Not passing the root node name to ``TreeBuilder`` was deprecated in Symfony 4.2.
+
 .. seealso::
 
     The ``Configuration`` class can be much more complicated than shown here,

diff --git a/components/browser_kit.rst b/components/browser_kit.rst
@@ -97,42 +97,77 @@ make AJAX requests::
 Clicking Links
 ~~~~~~~~~~~~~~
 
-The ``Crawler`` object is capable of simulating link clicks. First, pass the
-text content of the link to the ``selectLink()`` method, which returns a
-``Link`` object. Then, pass this object to the ``click()`` method, which
-performs the needed HTTP GET request to simulate the link click::
+The ``Client`` object is capable of simulating link clicks. Pass the text
+content of the link and the client will perform the needed HTTP GET request to
+simulate the link click::
 
     use Acme\Client;
 
     $client = new Client();
+    $client->request('GET', '/product/123');
+
+    $crawler = $client->clickLink('Go elsewhere...');
+
+.. versionadded:: 4.2
+    The ``clickLink()`` method was introduced in Symfony 4.2.
+
+If you need the :class:`Symfony\\Component\\DomCrawler\\Link` object that
+provides access to the link properties (e.g. ``$link->getMethod()``,
+``$link->getUri()``), use this other method:
+
+    // ...
     $crawler = $client->request('GET', '/product/123');
     $link = $crawler->selectLink('Go elsewhere...')->link();
     $client->click($link);
 
 Submitting Forms
 ~~~~~~~~~~~~~~~~
 
-The ``Crawler`` object is also capable of selecting forms. First, select any of
-the form's buttons with the ``selectButton()`` method. Then, use the ``form()``
-method to select the form which the button belongs to.
-
-After selecting the form, fill in its data and send it using the ``submit()``
-method (which makes the needed HTTP POST request to submit the form contents)::
+The ``Client`` object is also capable of submitting forms. First, select the
+form using any of its buttons and then override any of its properties (method,
+field values, etc.) before submitting it::
 
     use Acme\Client;
 
-    // make a real request to an external site
     $client = new Client();
     $crawler = $client->request('GET', 'https://github.com/login');
 
+    // find the form with the 'Log in' button and submit it
+    // 'Log in' can be the text content, id, value or name of a <button> or <input type="submit">
+    $client->submitForm('Log in');
+
+    // the second optional argument lets you override the default form field values
+    $client->submitForm('Log in', array(
+        'login' => 'my_user',
+        'password' => 'my_pass',
+        // to upload a file, the value must be the absolute file path
+        'file' => __FILE__,
+    ));
+
+    // you can override other form options too
+    $client->submitForm(
+        'Log in',
+        array('login' => 'my_user', 'password' => 'my_pass'),
+        // override the default form HTTP method
+        'PUT',
+        // override some $_SERVER parameters (e.g. HTTP headers)
+        array('HTTP_ACCEPT_LANGUAGE' => 'es')
+    );
+
+.. versionadded:: 4.2
+    The ``submitForm()`` method was introduced in Symfony 4.2.
+
+If you need the :class:`Symfony\\Component\\DomCrawler\\Form` object that
+provides access to the form properties (e.g. ``$form->getUri()``,
+``$form->getValues()``, ``$form->getFields()``), use this other method::
+
+    // ...
+
     // select the form and fill in some values
     $form = $crawler->selectButton('Log in')->form();
     $form['login'] = 'symfonyfan';
     $form['password'] = 'anypass';
 
-    // To upload a file, the value should be the absolute file path
-    $form['file'] = __FILE__;
-
     // submit that form
     $crawler = $client->submit($form);
 

diff --git a/components/cache/adapters/pdo_doctrine_dbal_adapter.rst b/components/cache/adapters/pdo_doctrine_dbal_adapter.rst
@@ -31,6 +31,15 @@ third, and forth parameters::
         $options = array()
     );
 
+.. versionadded:: 4.2
+    Automatic table creation was introduced in Symfony 4.2.
+
+The table where values are stored is created automatically on the first call to
+the :method:`Symfony\\Component\\Cache\\Adapter\\PdoAdapter::save` method.
+You can also create this table explicitly by calling the
+:method:`Symfony\\Component\\Cache\\Adapter\\PdoAdapter::createTable` method in
+your code.
+
 .. tip::
 
     When passed a `Data Source Name (DSN)`_ string (instead of a database connection

diff --git a/components/cache/adapters/redis_adapter.rst b/components/cache/adapters/redis_adapter.rst
@@ -96,9 +96,11 @@ array of ``key => value`` pairs representing option names and their respective v
 
         // associative array of configuration options
         array(
+            'compression' => true,
             'lazy' => false,
             'persistent' => 0,
             'persistent_id' => null,
+            'tcp_keepalive' => 0,
             'timeout' => 30,
             'read_timeout' => 0,
             'retry_interval' => 0,
@@ -114,6 +116,10 @@ Available Options
     If none is specified, it will return ``\Redis`` if the ``redis`` extension is
     available, and ``\Predis\Client`` otherwise.
 
+``compression`` (type: ``bool``, default: ``true``)
+    Enables or disables compression of items. This requires phpredis v4 or higher with
+    LZF support enabled.
+
 ``lazy`` (type: ``bool``, default: ``false``)
     Enables or disables lazy connections to the backend. It's ``false`` by
     default when using this as a stand-alone component and ``true`` by default
@@ -134,6 +140,10 @@ Available Options
     Specifies the delay (in milliseconds) between reconnection attempts in case the client
     loses connection with the server.
 
+``tcp_keepalive`` (type: ``int``, default: ``0``)
+    Specifies the `TCP-keepalive`_ timeout (in seconds) of the connection. This
+    requires phpredis v4 or higher and a TCP-keepalive enabled server.
+
 ``timeout`` (type: ``int``, default: ``30``)
     Specifies the time (in seconds) used to connect to a Redis server before the
     connection attempt times out.
@@ -149,3 +159,4 @@ Available Options
 .. _`RedisCluster`: https://github.com/phpredis/phpredis/blob/master/cluster.markdown#readme
 .. _`Predis`: https://packagist.org/packages/predis/predis
 .. _`Predis Connection Parameters`: https://github.com/nrk/predis/wiki/Connection-Parameters#list-of-connection-parameters
+.. _`TCP-keepalive`: https://redis.io/topics/clients#tcp-keepalive
diff --git a/components/config/definition.rst b/components/config/definition.rst
@@ -59,15 +59,18 @@ implements the :class:`Symfony\\Component\\Config\\Definition\\ConfigurationInte
     {
         public function getConfigTreeBuilder()
         {
-            $treeBuilder = new TreeBuilder();
-            $rootNode = $treeBuilder->root('database');
+            $treeBuilder = new TreeBuilder('database');
 
             // ... add node definitions to the root of the tree
+            // $treeBuilder->getRootNode()->...
 
             return $treeBuilder;
         }
     }
 
+.. versionadded:: 4.2
+    Not passing the root node name to ``TreeBuilder`` was deprecated in Symfony 4.2.
+
 Adding Node Definitions to the Tree
 -----------------------------------
 
@@ -534,10 +537,9 @@ tree with ``append()``::
 
     public function getConfigTreeBuilder()
     {
-        $treeBuilder = new TreeBuilder();
-        $rootNode = $treeBuilder->root('database');
+        $treeBuilder = new TreeBuilder('database');
 
-        $rootNode
+        $treeBuilder->getRootNode()
             ->children()
                 ->arrayNode('connection')
                     ->children()
@@ -564,10 +566,9 @@ tree with ``append()``::
 
     public function addParametersNode()
     {
-        $treeBuilder = new TreeBuilder();
-        $node = $treeBuilder->root('parameters');
+        $treeBuilder = new TreeBuilder('parameters');
 
-        $node
+        $treeBuilder->getRootNode()
             ->isRequired()
             ->requiresAtLeastOneElement()
             ->useAttributeAsKey('name')
@@ -795,10 +796,9 @@ Configuring the Node Path Separator
 
 Consider the following config builder example::
 
-    $treeBuilder = new TreeBuilder();
-    $rootNode = $treeBuilder->root('database');
+    $treeBuilder = new TreeBuilder('database');
 
-    $rootNode
+    $treeBuilder->getRootNode()
         ->children()
             ->arrayNode('connection')
                 ->children()

diff --git a/components/console/helpers/table.rst b/components/console/helpers/table.rst
@@ -66,6 +66,29 @@ You can add a table separator anywhere in the output by passing an instance of
     | 80-902734-1-6 | And Then There Were None | Agatha Christie  |
     +---------------+--------------------------+------------------+
 
+You can optionally display titles at the top and the bottom of the table::
+
+    // ...
+    $table->setHeaderTitle('Books')
+    $table->setFooterTitle('Page 1/2')
+    $table->render();
+
+.. code-block:: terminal
+
+    +---------------+----------- Books --------+------------------+
+    | ISBN          | Title                    | Author           |
+    +---------------+--------------------------+------------------+
+    | 99921-58-10-7 | Divine Comedy            | Dante Alighieri  |
+    | 9971-5-0210-0 | A Tale of Two Cities     | Charles Dickens  |
+    +---------------+--------------------------+------------------+
+    | 960-425-059-0 | The Lord of the Rings    | J. R. R. Tolkien |
+    | 80-902734-1-6 | And Then There Were None | Agatha Christie  |
+    +---------------+--------- Page 1/2 -------+------------------+
+
+.. versionadded:: 4.2
+    The ``setHeaderTitle()`` and ``setFooterTitle()`` methods were introduced
+    in Symfony 4.2.
+
 By default the width of the columns is calculated automatically based on their
 contents. Use the :method:`Symfony\\Component\\Console\\Helper\\Table::setColumnWidths`
 method to set the column widths explicitly::
@@ -76,7 +99,19 @@ method to set the column widths explicitly::
 
 In this example, the first column width will be ``10``, the last column width
 will be ``30`` and the second column width will be calculated automatically
-because of the ``0`` value. The output of this command will be:
+because of the ``0`` value.
+
+You can also set the width individually for each column with the
+:method:`Symfony\\Component\\Console\\Helper\\Table::setColumnWidth` method.
+Its first argument is the column index (starting from ``0``) and the second
+argument is the column width::
+
+    // ...
+    $table->setColumnWidth(0, 10);
+    $table->setColumnWidth(2, 30);
+    $table->render();
+
+The output of this command will be:
 
 .. code-block:: terminal
 
@@ -95,16 +130,30 @@ widths. If the contents don't fit, the given column width is increased up to the
 longest content length. That's why in the previous example the first column has
 a ``13`` character length although the user defined ``10`` as its width.
 
-You can also set the width individually for each column with the
-:method:`Symfony\\Component\\Console\\Helper\\Table::setColumnWidth` method.
-Its first argument is the column index (starting from ``0``) and the second
-argument is the column width::
+If you prefer to wrap long contents in multiple rows, use the
+:method:`Symfony\\Component\\Console\\Helper\\Table::setColumnMaxWidth` method::
 
     // ...
-    $table->setColumnWidth(0, 10);
-    $table->setColumnWidth(2, 30);
+    $table->setColumnMaxWidth(0, 5);
+    $table->setColumnMaxWidth(1, 10);
     $table->render();
 
+The output of this command will be:
+
+.. code-block:: terminal
+
+    +-------+------------+--------------------------------+
+    | ISBN  | Title      | Author                         |
+    +-------+------------+--------------------------------+
+    | 99921 | Divine Com | Dante Alighieri                |
+    | -58-1 | edy        |                                |
+    | 0-7   |            |                                |
+    |                (the rest of rows...)                |
+    +-------+------------+--------------------------------+
+
+.. versionadded:: 4.2
+    The ``setColumnMaxWidth()`` method was introduced in Symfony 4.2.
+
 The table style can be changed to any built-in styles via
 :method:`Symfony\\Component\\Console\\Helper\\Table::setStyle`::
 

diff --git a/components/dom_crawler.rst b/components/dom_crawler.rst
@@ -182,6 +182,13 @@ Get all the child or parent nodes::
     $crawler->filter('body')->children();
     $crawler->filter('body > p')->parents();
 
+Get all the direct child nodes matching a CSS selector::
+
+    $crawler->filter('body')->children('p.lorem');
+
+.. versionadded:: 4.2
+    The optional selector in ``children($selector)`` method was introduced in Symfony 4.2.
+
 .. note::
 
     All the traversal methods return a new :class:`Symfony\\Component\\DomCrawler\\Crawler`

diff --git a/components/dotenv.rst b/components/dotenv.rst
@@ -58,9 +58,14 @@ Access the value with ``getenv()`` in your code::
     $dbUser = getenv('DB_USER');
     // you can also use ``$_ENV`` or ``$_SERVER``
 
-.. note::
+The ``load()`` method never overwrites existing environment variables. Use the
+``overload()`` method if you need to overwrite them::
+
+    // ...
+    $dotenv->overload(__DIR__.'/.env');
 
-    Symfony Dotenv never overwrites existing environment variables.
+.. versionadded:: 4.2
+    The ``Dotenv::overload()`` method was introduced in Symfony 4.2.
 
 You should never store a ``.env`` file in your code repository as it might
 contain sensitive information; create a ``.env.dist`` file with sensible