minor #12951 Update Console Input Optional Options (Lopton)

javiereguiluz · javiereguiluz · commit c1e90437b957 · 2020-04-03T15:58:38.000+02:00
This PR was submitted for the 5.0 branch but it was merged into the 4.4 branch instead (closes #12951). Discussion ---------- Update Console Input Optional Options The documentation for the Option Input commands was not easy to follow. This leads to confusion such as in (symfony/symfony#29228). Modified to make it more clear what the different outcomes are and to provide a simple example before the condensed example. Commits ------- 7315664 Update input.rst
diff --git a/console/input.rst b/console/input.rst
@@ -247,11 +247,12 @@ optionally accepts a value, but it's a bit tricky. Consider this example::
         )
     ;
 
-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
+This option can be used in 3 ways: ``greet --yell``, ``greet yell=louder``, 
+and ``greet``. 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``::
+To solve this issue, you have to set the option's default value to 
+``false``::
 
     // ...
     use Symfony\Component\Console\Input\InputOption;
@@ -267,7 +268,32 @@ To solve this issue, you have to set the option's default value to ``false``::
         )
     ;
 
-Now check the value of the option and keep in mind that ``false !== null``::
+The input will now return the default value for the option when it is not 
+specified (``greet``), a null value when it is specified but not explicitly 
+defined  (``greet --yell``), and the defined value when defined  
+(``greet --yell=lounder``). Now check the value of the option::
+
+    $optionValue = $input->getOption('yell');
+    if ($optionValue === false ) {
+        // option was not specified
+        $yell = false;
+        $yellLouder = false;        
+    } elseif ($optionValue === null) {
+        // option was specified but no value given
+        $yell = true;
+        $yellLouder = false;        
+    } else {
+        // option was specified with a value which is now stored in $optionValue
+        $yell = true;
+        if ($optionValue === 'louder') {
+            $yellLouder = true;        
+        } else {
+            $yellLouder = false;        
+        }
+    }
+
+Once you are clear on how the default value is implemented you could consense the 
+above code into less lines of code since ``false !== null``::
 
     $optionValue = $input->getOption('yell');
     $yell = ($optionValue !== false);
