Merge remote-tracking branch 'upstream/master' into 4.2

Author: javiereguiluz

bundles/configuration.rst

@@ -198,6 +198,7 @@ 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::

components/asset.rst

@@ -375,9 +375,6 @@ document inside a template::
 Local Files and Other Protocols
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. versionadded:: 4.2
-    The support for other protocols was introduced in Symfony 4.2.
-
 In addition to HTTP this component supports other protocols (such as ``file://``
 and ``ftp://``). This allows for example to serve local files in order to
 improve performance::

components/browser_kit.rst

@@ -105,9 +105,6 @@ simulate the link click::
 
     $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:
@@ -151,9 +148,6 @@ field values, etc.) before submitting it::
         ['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::

components/cache/adapters/pdo_doctrine_dbal_adapter.rst

@@ -31,9 +31,6 @@ third, and forth parameters::
         $options = []
     );
 
-.. 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

components/config/definition.rst

@@ -69,6 +69,7 @@ implements the :class:`Symfony\\Component\\Config\\Definition\\ConfigurationInte
     }
 
 .. versionadded:: 4.2
+
     Not passing the root node name to ``TreeBuilder`` was deprecated in Symfony 4.2.
 
 Adding Node Definitions to the Tree

components/console/helpers/progressbar.rst

@@ -95,6 +95,33 @@ that the progress bar display is refreshed with a 100% completion.
     :method:`Symfony\\Component\\Console\\Helper\\ProgressBar::display`
     to show the progress bar again.
 
+If the progress information is stored in an iterable variable (such as an array
+or a PHP generator) you can use the
+:method:`Symfony\\Component\\Console\\Helper\\ProgressBar::iterate` method,
+which starts, advances and finishes the progress bar automatically::
+
+    use Symfony\Component\Console\Helper\ProgressBar;
+
+    $progressBar = new ProgressBar($output);
+
+    // $iterable can be for example an array ([1, 2, 3, ...]) or a generator
+    // $iterable = function () { yield 1; yield 2; ... };
+    foreach ($progressBar->iterate($iterable) as $value) {
+        // ... do some work
+    }
+
+If ``$iterable = [1, 2]``, the previous code will output the following:
+
+.. code-block:: terminal
+
+     0/2 [>---------------------------]   0%
+     1/2 [==============>-------------]  50%
+     2/2 [============================] 100%
+
+.. versionadded:: 4.3
+
+    The ``iterate()`` method was introduced in Symfony 4.3.
+
 Customizing the Progress Bar
 ----------------------------
 

components/console/helpers/table.rst

@@ -88,10 +88,6 @@ You can optionally display titles at the top and the bottom of the table::
     | 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::
@@ -154,9 +150,6 @@ The output of this command will be:
     |                (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`::
 

components/dom_crawler.rst

@@ -186,9 +186,6 @@ 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`
@@ -204,8 +201,16 @@ Access the node name (HTML tag name) of the first node of the current selection
 
 Access the value of the first node of the current selection::
 
+    // if the node does not exist, calling to text() will result in an exception
     $message = $crawler->filterXPath('//body/p')->text();
 
+    // avoid the exception passing an argument that text() returns when node does not exist
+    $message = $crawler->filterXPath('//body/p')->text('Default text content');
+
+.. versionadded:: 4.3
+
+    The default argument of ``text()`` was introduced in Symfony 4.3.
+
 Access the attribute value of the first node of the current selection::
 
     $class = $crawler->filterXPath('//body/p')->attr('class');
@@ -214,12 +219,17 @@ Extract attribute and/or node values from the list of nodes::
 
     $attributes = $crawler
         ->filterXpath('//body/p')
-        ->extract(['_text', 'class'])
+        ->extract(['_name', '_text', 'class'])
     ;
 
 .. note::
 
-    Special attribute ``_text`` represents a node value.
+    Special attribute ``_text`` represents a node value, while ``_name``
+    represents the element name (the HTML tag name).
+
+    .. versionadded:: 4.3
+
+        The special attribute ``_name`` was introduced in Symfony 4.3.
 
 Call an anonymous function on each node of the list::
 
@@ -296,8 +306,16 @@ and :phpclass:`DOMNode` objects::
     Or you can get the HTML of the first node using
     :method:`Symfony\\Component\\DomCrawler\\Crawler::html`::
 
+        // if the node does not exist, calling to html() will result in an exception
         $html = $crawler->html();
 
+        // avoid the exception passing an argument that html() returns when node does not exist
+        $html = $crawler->html('Default <strong>HTML</strong> content');
+
+    .. versionadded:: 4.3
+
+        The default argument of ``html()`` was introduced in Symfony 4.3.
+
 Expression Evaluation
 ~~~~~~~~~~~~~~~~~~~~~
 

components/dotenv.rst

@@ -64,9 +64,6 @@ The ``load()`` method never overwrites existing environment variables. Use the
     // ...
     $dotenv->overload(__DIR__.'/.env');
 
-.. 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
 defaults instead.

components/finder.rst

@@ -175,10 +175,6 @@ Sort the result by name or by type (directories first, then files)::
     as its argument to use PHP's `natural sort order`_ algorithm instead (e.g.
     ``file1.txt``, ``file2.txt``, ``file10.txt``).
 
-    .. versionadded:: 4.2
-
-        The option to use the natural sort order was introduced in Symfony 4.2.
-
 Sort the files and directories by the last accessed, changed or modified time::
 
     $finder->sortByAccessedTime();
@@ -198,10 +194,6 @@ You can reverse any sorting by using the ``reverseSorting()`` method::
     // results will be sorted "Z to A" instead of the default "A to Z"
     $finder->sortByName()->reverseSorting();
 
-.. versionadded:: 4.2
-
-    The ``reverseSorting()`` method was introduced in Symfony 4.2.
-
 .. note::
 
     Notice that the ``sort*`` methods need to get all matching elements to do
@@ -238,11 +230,6 @@ Multiple filenames can be excluded by chaining calls or passing an array::
     // same as above
     $finder->files()->notName(['*.rb', '*.py']);
 
-.. versionadded:: 4.2
-
-    Support for passing arrays to ``name()`` and ``notName()`` was introduced
-    in Symfony 4.2
-
 File Contents
 ~~~~~~~~~~~~~
 
@@ -285,10 +272,6 @@ Multiple paths can be defined by chaining calls or passing an array::
     // same as above
     $finder->path(['data', 'foo/bar']);
 
-.. versionadded:: 4.2
-
-    Support for passing arrays to ``path()`` was introduced in Symfony 4.2
-
 Internally, strings are converted into regular expressions by escaping slashes
 and adding delimiters:
 
@@ -328,10 +311,6 @@ Restrict by a size range by chaining calls or passing an array::
     // same as above
     $finder->files()->size(['>= 1K', '<= 2K']);
 
-.. versionadded:: 4.2
-
-    Support for passing arrays to ``size()`` was introduced in Symfony 4.2
-
 The comparison operator can be any of the following: ``>``, ``>=``, ``<``, ``<=``,
 ``==``, ``!=``.
 
@@ -354,10 +333,6 @@ Restrict by a date range by chaining calls or passing an array::
     // same as above
     $finder->date(['>= 2018-01-01', '<= 2018-12-31']);
 
-.. versionadded:: 4.2
-
-    Support for passing arrays to ``date()`` was introduced in Symfony 4.2
-
 The comparison operator can be any of the following: ``>``, ``>=``, ``<``, ``<=``,
 ``==``. You can also use ``since`` or ``after`` as an alias for ``>``, and
 ``until`` or ``before`` as an alias for ``<``.
@@ -380,10 +355,6 @@ Restrict by a depth range by chaining calls or passing an array::
     // same as above
     $finder->depth(['> 2', '< 5']);
 
-.. versionadded:: 4.2
-
-    Support for passing arrays to ``depth()`` was introduced in Symfony 4.2
-
 Custom Filtering
 ~~~~~~~~~~~~~~~~