Readded all 4.3 features

Author: javiereguiluz

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/dom_crawler.rst

@@ -204,6 +204,13 @@ 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');
@@ -212,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::
 
@@ -297,6 +309,13 @@ and :phpclass:`DOMNode` objects::
         // 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
 ~~~~~~~~~~~~~~~~~~~~~
 

configuration/external_parameters.rst

@@ -446,6 +446,15 @@ Symfony provides the following env var processors:
                 'auth' => '%env(file:AUTH_FILE)%',
             ]);
 
+``env(trim:FOO)``
+    Trims the content of ``FOO`` env var, removing whitespaces from the beginning
+    and end of the string. This is especially useful in combination with the
+    ``file`` processor, as it'll remove newlines at the end of a file.
+
+    .. versionadded:: 4.3
+
+        The ``trim`` processor was introduced in Symfony 4.3.
+
 ``env(key:FOO:BAR)``
     Retrieves the value associated with the key ``FOO`` from the array whose
     contents are stored in the ``BAR`` env var:
@@ -484,6 +493,50 @@ Symfony provides the following env var processors:
             $container->setParameter('env(SECRETS_FILE)', '/opt/application/.secrets.json');
             $container->setParameter('database_password', '%env(key:database_password:json:file:SECRETS_FILE)%');
 
+``env(default:fallback_param:BAR)``
+    Retrieves the value of the parameter ``fallback_param`` when the ``BAR`` env
+    var is not available:
+
+    .. configuration-block::
+
+        .. code-block:: yaml
+
+            # config/services.yaml
+            parameters:
+                # if PRIVATE_KEY is not a valid file path, the content of raw_key is returned
+                private_key: '%env(default:raw_key:file:PRIVATE_KEY)%'
+                raw_key: '%env(PRIVATE_KEY)%'
+
+        .. code-block:: xml
+
+            <!-- config/services.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:framework="http://symfony.com/schema/dic/symfony"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    http://symfony.com/schema/dic/services/services-1.0.xsd
+                    http://symfony.com/schema/dic/symfony
+                    http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                <parameters>
+                    <!-- if PRIVATE_KEY is not a valid file path, the content of raw_key is returned -->
+                    <parameter key="private_key">%env(default:raw_key:file:PRIVATE_KEY)%</parameter>
+                    <parameter key="raw_key">%env(PRIVATE_KEY)%</parameter>
+                </parameters>
+            </container>
+
+        .. code-block:: php
+
+            // config/services.php
+
+            // if PRIVATE_KEY is not a valid file path, the content of raw_key is returned
+            $container->setParameter('private_key', '%env(default:raw_key:file:PRIVATE_KEY)%');
+            $container->setParameter('raw_key', '%env(PRIVATE_KEY)%');
+
+    .. versionadded:: 4.3
+
+        The ``default`` processor was introduced in Symfony 4.3.
+
 It is also possible to combine any number of processors:
 
 .. code-block:: yaml

console/coloring.rst

@@ -74,8 +74,25 @@ You can also set these colors and options directly inside the tag name::
     or use the :method:`Symfony\\Component\\Console\\Formatter\\OutputFormatter::escape`
     method to escape all the tags included in the given string.
 
+Displaying Clickable Links
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 4.3
+    The feature to display clickable links was introduced in Symfony 4.3.
+
+Commands can use the special ``<href>`` tag to display links similar to the
+``<a>`` elements of web pages::
+
+    $output->writeln('<href=https://symfony.com>Symfony Homepage</>');
+
+If your terminal belongs to the `list of terminal emulators that support links`_
+you can click on the *"Symfony Homepage"* text to open its URL in your default
+browser. Otherwise, you'll see *"Symfony Homepage"* as regular text and the URL
+will be lost.
+
 .. _Cmder: http://cmder.net/
 .. _ConEmu: https://conemu.github.io/
 .. _ANSICON: https://github.com/adoxa/ansicon/releases
 .. _Mintty: https://mintty.github.io/
 .. _Hyper: https://hyper.is/
+.. _`list of terminal emulators that support links`: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda

form/create_custom_field_type.rst

@@ -99,6 +99,12 @@ The goal of this field was to extend the choice type to enable selection of the
 shipping type. This is achieved by fixing the ``choices`` to a list of available
 shipping options.
 
+.. tip::
+
+    If the purpose of this new form type was to customize the rendering of some
+    fields only, skip this step and use ``block_name`` or ``block_prefix`` options
+    instead to :ref:`define a custom form fragment name <form-fragment-custom-naming>`.
+
 .. tip::
 
     Run the following command to verify that the form type was successfully

form/form_themes.rst

@@ -275,6 +275,32 @@ form. You can also define this value explicitly with the ``block_name`` option::
 In this example, the fragment name will be ``_product_custom_name_widget``
 instead of the default ``_product_name_widget``.
 
+.. _form-fragment-custom-naming:
+
+Custom Fragment Naming for Individual Fields
+............................................
+
+The ``block_prefix`` option allows form fields to define their own custom
+fragment name. This is mostly useful to customize some instances of the same
+field without having to :doc:`create a custom form type </form/create_custom_field_type>`::
+
+    use Symfony\Component\Form\Extension\Core\Type\TextType;
+    use Symfony\Component\Form\FormBuilderInterface;
+
+    public function buildForm(FormBuilderInterface $builder, array $options)
+    {
+        $builder->add('name', TextType::class, array(
+            'block_prefix' => 'wrapped_text',
+        ));
+    }
+
+.. versionadded:: 4.3
+
+    The ``block_prefix`` option was introduced in Symfony 4.3.
+
+Now you can use ``wrapped_text_row``, ``wrapped_text_widget``, etc. as the block
+names.
+
 .. _form-custom-prototype:
 
 Fragment Naming for Collections

routing.rst

@@ -511,6 +511,14 @@ So how can you make ``blog_list`` once again match when the user visits
 Now, when the user visits ``/blog``, the ``blog_list`` route will match and
 ``$page`` will default to a value of ``1``.
 
+If you want to always include some default value in the generated URL (for
+example to force the generation of ``/blog/1`` instead of ``/blog`` in the
+previous example) add the ``!`` character before the placeholder name: ``/blog/{!page}``
+
+.. versionadded:: 4.3
+    The feature to force the inclusion of default values in generated URLs was
+    introduced in Symfony 4.3.
+
 As it happens with requirements, default values can also be inlined in each
 placeholder using the syntax ``{placeholder_name?default_value}``. This feature
 is compatible with inlined requirements, so you can inline both in a single

security/csrf.rst

@@ -108,6 +108,15 @@ this can be customized on a form-by-form basis::
         // ...
     }
 
+You can also customize the rendering of the CSRF form field creating a custom
+:doc:`form theme </form/form_themes>` and using ``csrf_token`` as the prefix of
+the field (e.g. define ``{% block csrf_token_widget %} ... {% endblock %}`` to
+customize the entire form field contents).
+
+.. versionadded:: 4.3
+
+    The ``csrf_token`` form field prefix was introduced in Symfony 4.3.
+
 CSRF Protection in Login Forms
 ------------------------------
 

service_container/alias_private.rst

@@ -146,6 +146,69 @@ This means that when using the container directly, you can access the
             # ...
             app.mailer: '@App\Mail\PhpMailer'
 
+Deprecating Service Aliases
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you decide to deprecate the use of a service alias (because it is outdated
+or you decided not to maintain it anymore), you can deprecate its definition:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        app.mailer:
+            alias: '@AppBundle\Mail\PhpMailer'
+
+            # this will display a generic deprecation message...
+            deprecated: true
+
+            # ...but you can also define a custom deprecation message
+            deprecated: 'The "%alias_id%" alias is deprecated. Don\'t use it anymore.'
+
+    .. code-block:: 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"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <service id="app.mailer" alias="App\Mail\PhpMailer">
+                    <!-- this will display a generic deprecation message... -->
+                    <deprecated />
+
+                    <!-- ...but you can also define a custom deprecation message -->
+                    <deprecated>The "%alias_id%" service alias is deprecated. Don't use it anymore.</deprecated>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        $container
+            ->setAlias('app.mailer', 'App\Mail\PhpMailer')
+
+            // this will display a generic deprecation message...
+            ->setDeprecated(true)
+
+            // ...but you can also define a custom deprecation message
+            ->setDeprecated(
+                true,
+                'The "%alias_id%" service alias is deprecated. Don\'t use it anymore.'
+            )
+        ;
+
+Now, every time this service alias is used, a deprecation warning is triggered,
+advising you to stop or to change your uses of that alias.
+
+The message is actually a message template, which replaces occurrences of the
+``%alias_id%`` placeholder by the service alias id. You **must** have at least
+one occurrence of the ``%alias_id%`` placeholder in your template.
+
+.. versionadded:: 4.3
+
+    The ``deprecated`` option for service aliases was introduced in Symfony 4.3.
+
 Anonymous Services
 ------------------