Merge branch '2.8' into 3.4

* 2.8:
  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
  Fix a typo in the HTML5 date form property
  Remove extra brace in the release schedule

Author: javiereguiluz

best_practices/tests.rst

@@ -12,7 +12,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
 ----------------
@@ -112,8 +112,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

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

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.