feature #4019 PhpdocTypesFixer - allow for configuration (keradus)

This PR was merged into the 2.12 branch.

Discussion
----------

PhpdocTypesFixer - allow for configuration

eg, `callback` alias type was in charge before 5.4, later it's not used.
eg `boolean`, usually may mean `bool` primitive, but sometimes it is a real custom class...

while for most cases it shall be fixed, there are few cases when not. let's make this configurable

ref sebastianbergmann/phpunit#3327

Commits
-------

3394dfc PhpdocTypesFixer - allow for configuration

README.rst

@@ -1464,6 +1464,11 @@ Choose from the list of available rules:
 
   The correct case must be used for standard PHP types in PHPDoc.
 
+  Configuration options:
+
+  - ``groups`` (a subset of ``['simple', 'alias', 'meta']``): type groups to fix;
+    defaults to ``['simple', 'alias', 'meta']``
+
 * **phpdoc_types_order**
 
   Sorts PHPDoc types.

src/Fixer/Phpdoc/PhpdocTypesFixer.php

@@ -13,46 +13,74 @@
 namespace PhpCsFixer\Fixer\Phpdoc;
 
 use PhpCsFixer\AbstractPhpdocTypesFixer;
+use PhpCsFixer\Fixer\ConfigurationDefinitionFixerInterface;
+use PhpCsFixer\FixerConfiguration\AllowedValueSubset;
+use PhpCsFixer\FixerConfiguration\FixerConfigurationResolver;
+use PhpCsFixer\FixerConfiguration\FixerOptionBuilder;
 use PhpCsFixer\FixerDefinition\CodeSample;
 use PhpCsFixer\FixerDefinition\FixerDefinition;
 
 /**
  * @author Graham Campbell <graham@alt-three.com>
+ * @author Dariusz Rumiński <dariusz.ruminski@gmail.com>
  */
-final class PhpdocTypesFixer extends AbstractPhpdocTypesFixer
+final class PhpdocTypesFixer extends AbstractPhpdocTypesFixer implements ConfigurationDefinitionFixerInterface
 {
     /**
-     * The types to process.
+     * Available types, grouped.
      *
-     * @var string[]
+     * @var array<string,string[]>
      */
-    private static $types = [
-        'array',
-        'bool',
-        'boolean',
-        'callable',
-        'callback',
-        'double',
-        'false',
-        'float',
-        'int',
-        'integer',
-        'iterable',
-        'mixed',
-        'null',
-        'object',
-        'parent',
-        'real',
-        'resource',
-        'scalar',
-        'self',
-        'static',
-        'string',
-        'true',
-        'void',
-        '$this',
+    private static $possibleTypes = [
+        'simple' => [
+            'array',
+            'bool',
+            'callable',
+            'float',
+            'int',
+            'iterable',
+            'null',
+            'object',
+            'string',
+        ],
+        'alias' => [
+            'boolean',
+            'callback',
+            'double',
+            'integer',
+            'real',
+        ],
+        'meta' => [
+            '$this',
+            'false',
+            'mixed',
+            'parent',
+            'resource',
+            'scalar',
+            'self',
+            'static',
+            'true',
+            'void',
+        ],
     ];
 
+    /**
+     * @var array string[]
+     */
+    private $typesToFix = [];
+
+    /**
+     * {@inheritdoc}
+     */
+    public function configure(array $configuration = null)
+    {
+        parent::configure($configuration);
+
+        $this->typesToFix = array_merge(...array_map(function ($group) {
+            return self::$possibleTypes[$group];
+        }, $this->configuration['groups']));
+    }
+
     /**
      * {@inheritdoc}
      */
@@ -94,10 +122,26 @@ protected function normalize($type)
     {
         $lower = strtolower($type);
 
-        if (\in_array($lower, self::$types, true)) {
+        if (\in_array($lower, $this->typesToFix, true)) {
             return $lower;
         }
 
         return $type;
     }
+
+    /**
+     * {@inheritdoc}
+     */
+    protected function createConfigurationDefinition()
+    {
+        $possibleGroups = array_keys(self::$possibleTypes);
+
+        return new FixerConfigurationResolver([
+            (new FixerOptionBuilder('groups', 'Type groups to fix.'))
+                ->setAllowedTypes(['array'])
+                ->setAllowedValues([new AllowedValueSubset($possibleGroups)])
+                ->setDefault($possibleGroups)
+                ->getOption(),
+        ]);
+    }
 }

tests/Fixer/Phpdoc/PhpdocTypesFixerTest.php

@@ -16,6 +16,7 @@
 
 /**
  * @author Graham Campbell <graham@alt-three.com>
+ * @author Dariusz Rumiński <dariusz.ruminski@gmail.com>
  *
  * @internal
  *
@@ -198,4 +199,38 @@ public function testInlineDoc()
 
         $this->doTest($expected, $input);
     }
+
+    public function testWithConfig()
+    {
+        $expected = <<<'EOF'
+<?php
+    /**
+     * @param self|array|Foo $bar
+     *
+     * @return int|float|callback
+     */
+
+EOF;
+
+        $input = <<<'EOF'
+<?php
+    /**
+     * @param SELF|Array|Foo $bar
+     *
+     * @return inT|Float|callback
+     */
+
+EOF;
+
+        $this->fixer->configure(['groups' => ['simple', 'meta']]);
+        $this->doTest($expected, $input);
+    }
+
+    public function testWrongConfig()
+    {
+        $this->expectException(\PhpCsFixer\ConfigurationException\InvalidFixerConfigurationException::class);
+        $this->expectExceptionMessageRegExp('/^\[phpdoc_types\] Invalid configuration: The option "groups" .*\.$/');
+
+        $this->fixer->configure(['groups' => ['__TEST__']]);
+    }
 }