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
 ~~~~~~~~~~~~~~~~
 

components/form.rst

@@ -759,9 +759,6 @@ method to access the list of errors. It returns a
 Clearing Form Errors
 ~~~~~~~~~~~~~~~~~~~~
 
-.. versionadded:: 4.2
-    The ``clearErrors()`` method was introduced in Symfony 4.2.
-
 Any errors can be manually cleared using the
 :method:`Symfony\\Component\\Form\\ClearableErrorsInterface::clearErrors`
 method. This is useful when you'd like to validate the form without showing

components/http_foundation.rst

@@ -551,9 +551,6 @@ abstracts the hard work behind a simple API::
 
     $response->headers->set('Content-Disposition', $disposition);
 
-.. versionadded:: 4.2
-    The static ``HeaderUtils::makeDisposition()`` method was introduced in Symfony 4.2.
-
 Alternatively, if you are serving a static file, you can use a
 :class:`Symfony\\Component\\HttpFoundation\\BinaryFileResponse`::
 

components/ldap.rst

@@ -166,8 +166,4 @@ Possible operation types are ``LDAP_MODIFY_BATCH_ADD``, ``LDAP_MODIFY_BATCH_REMO
 ``$values`` must be ``NULL`` when using ``LDAP_MODIFY_BATCH_REMOVE_ALL``
 operation type.
 
-.. versionadded:: 4.2
-
-    The ``applyOperations()`` method was introduced in Symfony 4.2.
-
 .. _Packagist: https://packagist.org/packages/symfony/ldap

components/lock.rst

@@ -220,9 +220,6 @@ support blocking, and expects a TTL to avoid stalled locks::
 PdoStore
 ~~~~~~~~
 
-.. versionadded:: 4.2
-    The PdoStore was introduced Symfony 4.2.
-
 The PdoStore saves locks in an SQL database. It requires a `PDO`_ connection, a
 `Doctrine DBAL Connection`_, or a `Data Source Name (DSN)`_. This store does not
 support blocking, and expects a TTL to avoid stalled locks::
@@ -326,9 +323,6 @@ the stores.
 ZookeeperStore
 ~~~~~~~~~~~~~~
 
-.. versionadded:: 4.2
-    The ZookeeperStore was introduced in Symfony 4.2.
-
 The ZookeeperStore saves locks on a `ZooKeeper`_ server. It requires a ZooKeeper
 connection implementing the ``\Zookeeper`` class. This store does not
 support blocking and expiration but the lock is automatically released when the

components/options_resolver.rst

@@ -637,9 +637,6 @@ let you find out which options are defined::
 Nested Options
 ~~~~~~~~~~~~~~
 
-.. versionadded:: 4.2
-    The support of nested options was introduced in Symfony 4.2.
-
 Suppose you have an option named ``spool`` which has two sub-options ``type``
 and ``path``. Instead of defining it as a simple array of values, you can pass a
 closure as the default value of the ``spool`` option with a
@@ -732,9 +729,6 @@ In same way, parent options can access to the nested options as normal arrays::
 Deprecating the Option
 ~~~~~~~~~~~~~~~~~~~~~~
 
-.. versionadded:: 4.2
-    The ``setDeprecated()`` method was introduced in Symfony 4.2.
-
 Once an option is outdated or you decided not to maintain it anymore, you can
 deprecate it using the :method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::setDeprecated`
 method::

components/phpunit_bridge.rst

@@ -248,9 +248,6 @@ class autoloading time. This can be disabled with the ``debug-class-loader`` opt
         </listener>
     </listeners>
 
-.. versionadded:: 4.2
-    The ``DebugClassLoader`` integration was introduced in Symfony 4.2.
-
 Write Assertions about Deprecations
 -----------------------------------
 

components/process.rst

@@ -100,10 +100,6 @@ with a non-zero code)::
 Using Features From the OS Shell
 --------------------------------
 
-.. versionadded:: 4.2
-
-    The ``fromShellCommandline()`` static method was introduced in Symfony 4.2.
-
 Using array of arguments is the recommended way to define commands. This
 saves you from any escaping and allows sending signals seamlessly
 (e.g. to stop processes before completion)::
@@ -240,9 +236,6 @@ process and checks its output to wait until its fully initialized::
 
     // ... do things after the process is ready
 
-.. versionadded:: 4.2
-    The ``waitUntil()`` method was introduced in Symfony 4.2.
-
 Streaming to the Standard Input of a Process
 --------------------------------------------
 

components/property_info.rst

@@ -77,10 +77,6 @@ provide it with a set of information extractors.
     $class = YourAwesomeCoolClass::class;
     $properties = $propertyInfo->getProperties($class);
 
-.. versionadded:: 4.2
-    :class:`Symfony\\Component\\PropertyInfo\\PropertyInitializableExtractorInterface`
-    was introduced in Symfony 4.2.
-
 Extractor Ordering
 ~~~~~~~~~~~~~~~~~~
 
@@ -490,11 +486,6 @@ with the ``property_info`` service in the Symfony Framework.
     // Type information.
     $doctrineExtractor->getTypes($class, $property);
 
-.. versionadded:: 4.2
-    The option to pass Doctrine's EntityManager to ``DoctrineExtractor`` was
-    introduced in Symfony 4.2. Previously you needed to pass the class metadata
-    factory associated to the EntityManager.
-
 .. _`components-property-information-extractors-creation`:
 
 Creating Your Own Extractors