Merge branch '4.1'

* 4.1: (28 commits)
  Removed an outdated section
  Reorganized the contents of the new output sections
  Add documentation about manipulating console output
  Update deployment.rst
  Update the security reference because user providers are no longer mandatory
  Update typescript.rst
  Corrected titles of test tools and use safe url for phpspec
  Add 2 solutions for the 'option with optional argument' problem
  Simplify the explanation leaving just one solution
  Add 2 solutions for the 'option with optional argument' problem
  ocramius/proxy-manager isn't needed anymore
  Fix a typo in the HTML5 date form property
  Add URL-encoding notice
  ...

Author: javiereguiluz

best_practices/tests.rst

@@ -13,7 +13,7 @@ Unit Tests
 Unit tests are used to test your "business logic", which should live in classes
 that are independent of Symfony. For that reason, Symfony doesn't really
 have an opinion on what tools you use for unit testing. However, the most
-popular tools are `PhpUnit`_ and `PhpSpec`_.
+popular tools are `PHPUnit`_ and `PHPSpec`_.
 
 Functional Tests
 ----------------
@@ -114,8 +114,8 @@ Learn More about Functional Tests
 Consider using the `HautelookAliceBundle`_ to generate real-looking data for
 your test fixtures using `Faker`_ and `Alice`_.
 
-.. _`PhpUnit`: https://phpunit.de/
-.. _`PhpSpec`: http://www.phpspec.net/
+.. _`PHPUnit`: https://phpunit.de/
+.. _`PHPSpec`: https://www.phpspec.net/
 .. _`smoke testing`: https://en.wikipedia.org/wiki/Smoke_testing_(software)
 .. _`Mink`: http://mink.behat.org
 .. _`HautelookAliceBundle`: https://github.com/hautelook/AliceBundle

components/console/helpers/progressbar.rst

@@ -342,3 +342,43 @@ of the custom placeholders::
         $progressBar->advance();
         // 2/100 -- Importing invoices... (client-001/invoices.xml)
     }
+
+.. _console-multiple-progress-bars:
+
+Displaying Multiple Progress Bars
+---------------------------------
+
+.. versionadded:: 4.1
+    The feature to display multiple progress bars using output sections was
+    introduced in Symfony 4.1.
+
+When using :ref:`Console output sections <console-output-sections>` it's
+possible to display multiple progress bars at the same time and change their
+progress independently::
+
+    $section1 = $output->section();
+    $section2 = $output->section();
+
+    $progress1 = new ProgressBar($section1);
+    $progress2 = new ProgressBar($section2);
+
+    $progress1->start(100);
+    $progress2->start(100);
+
+    $i = 0;
+    while (++$i < 100) {
+        $progress1->advance();
+
+        if ($i % 2 === 0) {
+            $progress2->advance(4);
+        }
+
+        usleep(50000);
+    }
+
+After a couple of iterations, the output in the terminal will look like this:
+
+.. code-block:: text
+
+    34/100 [=========>------------------]  34%
+    68/100 [===================>--------]  68%

components/console/helpers/table.rst

@@ -324,3 +324,47 @@ This outputs:
 
 You can use the ``colspan`` and ``rowspan`` options at the same time which allows
 you to create any table layout you may wish.
+
+.. _console-modify-rendered-tables:
+
+Modifying Rendered Tables
+-------------------------
+
+.. versionadded:: 4.1
+    The feature to modify rendered tables was introduced in Symfony 4.1.
+
+The ``render()`` method requires passing the entire table contents. However,
+sometimes that information is not available beforehand because it's generated
+dynamically. In those cases, use the
+:method:`Symfony\\Component\\Console\\Helper\\Table::appendRow` method, which
+takes the same arguments as the ``addRow()`` method, to add rows at the bottom
+of an already rendered table.
+
+The only requirement to append rows is that the table must be rendered inside a
+:ref:`Console output section <console-output-sections>`::
+
+    use Symfony\Component\Console\Helper\Table;
+    // ...
+
+    class SomeCommand extends Command
+    {
+        public function execute(InputInterface $input, OutputInterface $output)
+        {
+            $section = $output->section();
+            $table = new Table($section);
+
+            $table->addRow(['Row 1']);
+            $table->render();
+
+            $table->addRow(['Row 2']);
+        }
+    }
+
+This will display the following table in the terminal:
+
+.. code-block:: terminal
+
+    +-------+
+    | Row 1 |
+    | Row 2 |
+    +-------+

console.rst

@@ -87,9 +87,13 @@ After configuring and registering the command, you can execute it in the termina
     $ php bin/console app:create-user
 
 As you might expect, this command will do nothing as you didn't write any logic
-yet. Add your own logic inside the ``execute()`` method, which has access to the
-input stream (e.g. options and arguments) and the output stream (to write
-messages to the console)::
+yet. Add your own logic inside the ``execute()`` method.
+
+Console Output
+--------------
+
+The ``execute()`` method has access to the output stream to write messages to
+the console::
 
     // ...
     protected function execute(InputInterface $input, OutputInterface $output)
@@ -128,6 +132,57 @@ Now, try executing the command:
     Whoa!
     You are about to create a user.
 
+.. _console-output-sections:
+
+Output Sections
+~~~~~~~~~~~~~~~
+
+.. versionadded:: 4.1
+    Output sections were introduced in Symfony 4.1.
+
+The regular console output can be divided into multiple independent regions
+called "output sections". Create one or more of these sections when you need to
+clear and overwrite the output information.
+
+Sections are created with the
+:method:`Symfony\\Component\\Console\\Output\\ConsoleOutput::section` method,
+which returns an instance of
+:class:`Symfony\\Component\\Console\\Output\\ConsoleSectionOutput`::
+
+    class MyCommand extends Command
+    {
+        protected function execute(InputInterface $input, OutputInterface $output)
+        {
+            $section1 = $output->section();
+            $section2 = $output->section();
+            $section1->writeln('Hello');
+            $section2->writeln('World!');
+            // Output displays "Hello\nWorld!\n"
+
+            // overwrite() replaces all the existing section contents with the given content
+            $section1->overwrite('Goodbye');
+            // Output now displays "Goodbye\nWorld!\n"
+
+            // clear() deletes all the section contents...
+            $section2->clear();
+            // Output now displays "Goodbye\n"
+
+            // ...but you can also delete a given number of lines
+            // (this example deletes the last two lines of the section)
+            $section1->clear(2);
+            // Output is now completely empty!
+        }
+    }
+
+.. note::
+
+    A new line is appended automatically when displaying information in a section.
+
+Output sections let you manipulate the Console output in advanced ways, such as
+:ref:`displaying multiple progress bars <console-multiple-progress-bars>` which
+are updated independently and :ref:`appending rows to tables <console-modify-rendered-tables>`
+that have already been rendered.
+
 Console Input
 -------------
 

console/input.rst

@@ -179,6 +179,15 @@ values after a white space or an ``=`` sign (e.g. ``--iterations 5`` or
 ``--iterations=5``), but short options can only use white spaces or no
 separation at all (e.g. ``-i 5`` or ``-i5``).
 
+.. caution::
+
+    While it is possible to separate an option from its value with a white space,
+    using this form leads to an ambiguity should the option appear before the
+    command name. For example, ``php app/console --iterations 5 app:greet Fabien``
+    is ambiguous; Symfony would interpret ``5`` as the command name. To avoid
+    this situation, always place options after the command name, or avoid using
+    a space to separate the option name from its value.
+
 There are four option variants you can use:
 
 ``InputOption::VALUE_IS_ARRAY``
@@ -209,21 +218,53 @@ You can combine ``VALUE_IS_ARRAY`` with ``VALUE_REQUIRED`` or
             array('blue', 'red')
         );
 
-.. tip::
+Options with optional arguments
+-------------------------------
+
+There is nothing forbidding you to create a command with an option that
+optionally accepts a value, but it's a bit tricky. Consider this example::
+
+    // ...
+    use Symfony\Component\Console\Input\InputOption;
+
+    $this
+        // ...
+        ->addOption(
+            'yell',
+            null,
+            InputOption::VALUE_OPTIONAL,
+            'Should I yell while greeting?'
+        );
+
+This option can be used in 3 ways: ``--yell``, ``yell=louder``, and not passing
+the option at all. However, it's hard to distinguish between passing the option
+without a value (``greet --yell``) and not passing the option (``greet``).
+
+To solve this issue, you have to set the option's default value to ``false``::
+
+    // ...
+    use Symfony\Component\Console\Input\InputOption;
+
+    $this
+        // ...
+        ->addOption(
+            'yell',
+            null,
+            InputOption::VALUE_OPTIONAL,
+            'Should I yell while greeting?',
+            false // this is the new default value, instead of null
+        );
 
-    There is nothing forbidding you to create a command with an option that
-    optionally accepts a value. However, there is no way you can distinguish
-    when the option was used without a value (``command --language``) or when
-    it wasn't used at all (``command``). In both cases, the value retrieved for
-    the option will be ``null``.
+Now check the value of the option and keep in mind that ``false !== null``::
+
+    $optionValue = $input->getOptions('yell');
+    $yell = ($optionValue !== false);
+    $yellLouder = ($optionValue === 'louder');
 
 .. caution::
 
-    While it is possible to separate an option from its value with a white space,
-    using this form leads to an ambiguity should the option appear before the
-    command name. For example, ``php bin/console --iterations 5 app:greet Fabien``
-    is ambiguous; Symfony would interpret ``5`` as the command name. To avoid
-    this situation, always place options after the command name, or avoid using
-    a space to separate the option name from its value.
+    Due to a PHP limitation, passing an empty string is indistinguishable from
+    not passing any value at all. In ``command --prefix`` and ``command --prefix=''``
+    cases, the value of the ``prefix`` option will be ``null``.
 
 .. _`docopt standard`: http://docopt.org/

contributing/community/releases.rst

@@ -122,7 +122,7 @@ Version       Feature Freeze  Release  End of Maintenance        End of Life
 `2.6`_        09/2014         11/2014  07/2015 (8 months)        01/2016
 `2.7`_ (LTS)  03/2015         05/2015  05/2018 (36 months)       05/2019
 `2.8`_ (LTS)  09/2015         11/2015  11/2018 (36 months [2]_)  11/2019
-`3.0`_        09/2015         11/2015  07/2016 (8 months) [3]_)  01/2017
+`3.0`_        09/2015         11/2015  07/2016 (8 months [3]_)   01/2017
 `3.1`_        03/2016         05/2016  01/2017 (8 months)        07/2017
 `3.2`_        09/2016         11/2016  07/2017 (8 months)        01/2018
 `3.3`_        03/2017         05/2017  01/2018 (8 months)        07/2018
@@ -194,7 +194,7 @@ version is published every two years and there is a year to upgrade.
 
 .. _Semantic Versioning: https://semver.org/
 .. _Git repository: https://github.com/symfony/symfony
-.. _SensioLabs:     http://sensiolabs.com/
+.. _SensioLabs:     https://sensiolabs.com/
 .. _roadmap notification: https://symfony.com/roadmap
 .. _extended to September 2014: https://symfony.com/blog/extended-maintenance-for-symfony-2-4
 .. _timeline calculator: https://symfony.com/roadmap#checker

deployment.rst

@@ -116,11 +116,8 @@ you'll need to do:
 A) Check Requirements
 ~~~~~~~~~~~~~~~~~~~~~
 
-Check if your server meets the requirements by running:
-
-.. code-block:: terminal
-
-    $ php bin/symfony_requirements
+Use the :doc:`Symfony Requirements Checker </reference/requirements>` to check
+if your server meets the technical requirements to run Symfony applications.
 
 .. _b-configure-your-app-config-parameters-yml-file:
 

email.rst

@@ -37,7 +37,9 @@ environment variable in the ``.env`` file:
     # use this to disable email delivery
     MAILER_URL=null://localhost
 
-    # use this to configure a traditional SMTP server
+    # use this to configure a traditional SMTP server (make sure to URL-encode the
+    # values of the username and password if they contain non-alphanumeric characters
+    # such as '+', '@', ':' and '*', which are reserved in URLs)
     MAILER_URL=smtp://localhost:25?encryption=ssl&auth_mode=login&username=&password=
 
 Refer to the :doc:`SwiftMailer configuration reference </reference/configuration/swiftmailer>`

frontend/encore/typescript.rst

@@ -28,7 +28,7 @@ also configure the `ts-loader options`_ via a callback:
 
     .enableTypeScriptLoader(function (typeScriptConfigOptions) {
         typeScriptConfigOptions.transpileOnly = true;
-        typeScriptConfigOptions.configFileName = '/path/to/tsconfig.json';
+        typeScriptConfigOptions.configFile = '/path/to/tsconfig.json';
     });
 
 If React assets are enabled (``.enableReactPreset()``), any ``.tsx`` file will be

messenger.rst

@@ -623,7 +623,7 @@ factories. Using them requires a two-step configuration based on Symfony's
             arguments: ['@doctrine']
 
         # Step 2: an abstract definition that will call the factory with default
-        # arguments or the one provided in the middleware config
+        # arguments or the ones provided in the middleware config
         messenger.middleware.doctrine_transaction_middleware:
             class: Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddleware
             factory: ['@doctrine.orm.messenger.middleware_factory.transaction', 'createMiddleware']
@@ -650,9 +650,9 @@ Then you can reference and configure the
                 buses:
                     command_bus:
                         middleware:
-                            # Using defaults:
+                            # Using defaults
                             - doctrine_transaction_middleware
-                            # Using another entity manager:
+                            # Using another entity manager
                             - doctrine_transaction_middleware: ['custom']
 
     .. code-block:: xml
@@ -669,7 +669,7 @@ Then you can reference and configure the
             <framework:config>
                 <framework:messenger>
                     <framework:bus name="command_bus">
-                        <!-- Using defaults: -->
+                        <!-- Using defaults -->
                         <framework:middleware id="doctrine_transaction_middleware" />
                         <!-- Using another entity manager -->
                         <framework:middleware id="doctrine_transaction_middleware">
@@ -688,7 +688,7 @@ Then you can reference and configure the
                 'buses' => array(
                     'command_bus' => array(
                         'middleware' => array(
-                            // Using defaults:
+                            // Using defaults
                             'doctrine_transaction_middleware',
                             // Using another entity manager
                             array('id' => 'doctrine_transaction_middleware', 'arguments' => array('custom')),

reference/configuration/security.rst

@@ -72,7 +72,7 @@ Each part will be explained in the next section.
                     time_cost:            2 # Number of iterations
                     threads:              2 # Number of parallel threads
 
-            providers:            # Required
+            providers:
                 # Examples:
                 my_in_memory_provider:
                     memory:
@@ -301,6 +301,9 @@ Each part will be explained in the next section.
                 ROLE_ADMIN:      [ROLE_ORGANIZER, ROLE_USER]
                 ROLE_SUPERADMIN: [ROLE_ADMIN]
 
+.. versionadded:: 4.1
+    The ``providers`` option is optional starting from Symfony 4.1.
+
 .. _reference-security-firewall-form-login:
 
 Form Login Configuration

reference/forms/types/options/html5.rst.inc

@@ -6,5 +6,5 @@ html5
 If this is set to ``true`` (the default), it'll use the HTML5 type (date, time
 or datetime) to render the field. When set to ``false``, it'll use the text type.
 
-This is useful when you want to use a custom JavaScript datapicker, which
+This is useful when you want to use a custom JavaScript datepicker, which
 often requires a text type instead of an HTML5 type.