minor #3578 Add interface for deprecated options (julienfalque, keradus)

This PR was squashed before being merged into the 2.11 branch (closes #3578).

Discussion
----------

Add interface for deprecated options

Commits
-------

f2d28224 Add interface for deprecated options

README.rst

@@ -271,10 +271,12 @@ Choose from the list of available rules:
 
   Configuration options:
 
-  - ``align_double_arrow`` (``false``, ``null``, ``true``): (deprecated) Whether to apply,
-    remove or ignore double arrows alignment; defaults to ``false``
-  - ``align_equals`` (``false``, ``null``, ``true``): (deprecated) Whether to apply, remove
-    or ignore equals alignment; defaults to ``false``
+  - ``align_double_arrow`` (``false``, ``null``, ``true``): whether to apply, remove or
+    ignore double arrows alignment; defaults to ``false``. DEPRECATED: use
+    options ``operators`` and ``default`` instead
+  - ``align_equals`` (``false``, ``null``, ``true``): whether to apply, remove or ignore
+    equals alignment; defaults to ``false``. DEPRECATED: use options
+    ``operators`` and ``default`` instead
   - ``default`` (``'align'``, ``'align_single_space'``, ``'align_single_space_minimal'``,
     ``'single_space'``, ``null``): default fix strategy; defaults to ``'single_space'``
   - ``operators`` (``array``): dictionary of ``binary operator`` => ``fix strategy``
@@ -517,12 +519,13 @@ Choose from the list of available rules:
   - ``after_array_assignments_equals`` (``null``, ``bool``): whether to add, remove or
     ignore spaces after array assignment ``=`` operator; defaults to ``true``
   - ``around_argument_assignments`` (``bool``): whether to fix spaces around
-    argument assignment operator (deprecated, use
-    ``before_argument_assignments`` and ``after_argument_assignments`` options
-    instead); defaults to ``true``
+    argument assignment operator; defaults to ``true``. DEPRECATED: use options
+    ``before_argument_assignments`` and ``after_argument_assignments`` instead
   - ``around_array_assignments`` (``bool``): whether to fix spaces around array
-    assignment operators (deprecated, use ``before_array_assignments_*`` and
-    ``after_array_assignments_*`` options instead); defaults to ``true``
+    assignment operators; defaults to ``true``. DEPRECATED: use options
+    ``before_array_assignments_equals``, ``after_array_assignments_equals``,
+    ``before_array_assignments_colon`` and ``after_array_assignments_colon``
+    instead
   - ``around_commas`` (``bool``): whether to fix spaces around commas; defaults to
     ``true``
   - ``around_parentheses`` (``bool``): whether to fix spaces around parentheses;
@@ -701,8 +704,8 @@ Choose from the list of available rules:
 
   Configuration options:
 
-  - ``use_yoda_style`` (``bool``): (deprecated) Whether Yoda style conditions should
-    be used; defaults to ``true``
+  - ``use_yoda_style`` (``bool``): whether Yoda style conditions should be used;
+    defaults to ``true``. DEPRECATED: use ``yoda_style`` fixer instead
 
 * **line_ending** [@PSR2, @Symfony]
 
@@ -1094,8 +1097,8 @@ Choose from the list of available rules:
 
   Configuration options:
 
-  - ``functions`` (``null``): (deprecated, use ``target`` instead) List of assertions
-    to fix (overrides ``target``); defaults to ``null``
+  - ``functions`` (``null``): list of assertions to fix (overrides ``target``);
+    defaults to ``null``. DEPRECATED: use option ``target`` instead
   - ``target`` (``'3.0'``, ``'3.5'``, ``'5.0'``, ``'5.6'``, ``'newest'``): target version of
     PHPUnit; defaults to ``'5.0'``
 

src/AbstractFixer.php

@@ -15,11 +15,13 @@ namespace PhpCsFixer;
 use PhpCsFixer\ConfigurationException\InvalidFixerConfigurationException;
 use PhpCsFixer\ConfigurationException\InvalidForEnvFixerConfigurationException;
 use PhpCsFixer\ConfigurationException\RequiredFixerConfigurationException;
+use PhpCsFixer\Console\Application;
 use PhpCsFixer\Fixer\ConfigurableFixerInterface;
 use PhpCsFixer\Fixer\ConfigurationDefinitionFixerInterface;
 use PhpCsFixer\Fixer\DefinedFixerInterface;
 use PhpCsFixer\Fixer\FixerInterface;
 use PhpCsFixer\Fixer\WhitespacesAwareFixerInterface;
+use PhpCsFixer\FixerConfiguration\DeprecatedFixerOption;
 use PhpCsFixer\FixerConfiguration\FixerConfigurationResolverInterface;
 use PhpCsFixer\FixerConfiguration\InvalidOptionsForEnvException;
 use PhpCsFixer\Tokenizer\Tokens;
@@ -128,6 +130,22 @@ abstract class AbstractFixer implements FixerInterface, DefinedFixerInterface
             $configuration = [];
         }
 
+        foreach ($this->getConfigurationDefinition()->getOptions() as $option) {
+            if (!$option instanceof DeprecatedFixerOption) {
+                continue;
+            }
+
+            $name = $option->getName();
+            if (array_key_exists($name, $configuration)) {
+                @trigger_error(sprintf(
+                    'Option "%s" is deprecated and will be removed in %d.0. %s',
+                    $name,
+                    Application::VERSION + 1,
+                    str_replace('`', '"', $option->getDeprecationMessage())
+                ), E_USER_DEPRECATED);
+            }
+        }
+
         try {
             $this->configuration = $this->getConfigurationDefinition()->resolve($configuration);
         } catch (MissingOptionsException $exception) {

src/Console/Command/DescribeCommand.php

@@ -19,6 +19,7 @@ use PhpCsFixer\Fixer\ConfigurationDefinitionFixerInterface;
 use PhpCsFixer\Fixer\DefinedFixerInterface;
 use PhpCsFixer\Fixer\DeprecatedFixerInterface;
 use PhpCsFixer\Fixer\FixerInterface;
+use PhpCsFixer\FixerConfiguration\DeprecatedFixerOption;
 use PhpCsFixer\FixerDefinition\CodeSampleInterface;
 use PhpCsFixer\FixerDefinition\FileSpecificCodeSampleInterface;
 use PhpCsFixer\FixerDefinition\FixerDefinition;
@@ -210,6 +211,14 @@ final class DescribeCommand extends Command
                     $line .= '<comment>required</comment>';
                 }
 
+                if ($option instanceof DeprecatedFixerOption) {
+                    $line .= '. <error>DEPRECATED</error>: '.Preg::replace(
+                        '/(`.+?`)/',
+                        '<info>$1</info>',
+                        OutputFormatter::escape(lcfirst($option->getDeprecationMessage()))
+                    );
+                }
+
                 $output->writeln($line);
             }
 

src/Console/Command/HelpCommand.php

@@ -18,6 +18,7 @@ use PhpCsFixer\Fixer\ConfigurationDefinitionFixerInterface;
 use PhpCsFixer\Fixer\DefinedFixerInterface;
 use PhpCsFixer\Fixer\DeprecatedFixerInterface;
 use PhpCsFixer\Fixer\FixerInterface;
+use PhpCsFixer\FixerConfiguration\DeprecatedFixerOption;
 use PhpCsFixer\FixerConfiguration\FixerOptionInterface;
 use PhpCsFixer\FixerFactory;
 use PhpCsFixer\Preg;
@@ -537,6 +538,14 @@ EOF
                             $line .= 'required';
                         }
 
+                        if ($option instanceof DeprecatedFixerOption) {
+                            $line .= '. DEPRECATED: '.Preg::replace(
+                                '/(`.+?`)/',
+                                '<info>$1</info>',
+                                lcfirst(Preg::replace('/\.$/', '', OutputFormatter::escape($option->getDeprecationMessage())))
+                            );
+                        }
+
                         foreach (self::wordwrap($line, 72) as $index => $line) {
                             $help .= (0 === $index ? '   | - ' : '   |   ').$line."\n";
                         }

src/Fixer/DoctrineAnnotation/DoctrineAnnotationSpacesFixer.php

@@ -47,15 +47,6 @@ final class DoctrineAnnotationSpacesFixer extends AbstractDoctrineAnnotationFixe
     {
         parent::configure($configuration);
 
-        if (null !== $configuration) {
-            if (array_key_exists('around_argument_assignments', $configuration)) {
-                @trigger_error('Option "around_argument_assignments" is deprecated and will be removed in 3.0, use options "before_argument_assignments" and "after_argument_assignments" instead.', E_USER_DEPRECATED);
-            }
-            if (array_key_exists('around_array_assignments', $configuration)) {
-                @trigger_error('Option "around_array_assignments" is deprecated and will be removed in 3.0, use options "before_array_assignments_equals", "after_array_assignments_equals", "before_array_assignments_colon" and "after_array_assignments_colon" instead.', E_USER_DEPRECATED);
-            }
-        }
-
         if (!$this->configuration['around_argument_assignments']) {
             foreach ([
                 'before_argument_assignments',
@@ -97,9 +88,10 @@ final class DoctrineAnnotationSpacesFixer extends AbstractDoctrineAnnotationFixe
                     ->setAllowedTypes(['bool'])
                     ->setDefault(true)
                     ->getOption(),
-                (new FixerOptionBuilder('around_argument_assignments', 'Whether to fix spaces around argument assignment operator (deprecated, use `before_argument_assignments` and `after_argument_assignments` options instead).'))
+                (new FixerOptionBuilder('around_argument_assignments', 'Whether to fix spaces around argument assignment operator.'))
                     ->setAllowedTypes(['bool'])
                     ->setDefault(true)
+                    ->setDeprecationMessage('Use options `before_argument_assignments` and `after_argument_assignments` instead.')
                     ->getOption(),
                 (new FixerOptionBuilder('before_argument_assignments', 'Whether to add, remove or ignore spaces before argument assignment operator.'))
                     ->setAllowedTypes(['null', 'bool'])
@@ -109,9 +101,10 @@ final class DoctrineAnnotationSpacesFixer extends AbstractDoctrineAnnotationFixe
                     ->setAllowedTypes(['null', 'bool'])
                     ->setDefault(false)
                     ->getOption(),
-                (new FixerOptionBuilder('around_array_assignments', 'Whether to fix spaces around array assignment operators (deprecated, use `before_array_assignments_*` and `after_array_assignments_*` options instead).'))
+                (new FixerOptionBuilder('around_array_assignments', 'Whether to fix spaces around array assignment operators.'))
                     ->setAllowedTypes(['bool'])
                     ->setDefault(true)
+                    ->setDeprecationMessage('Use options `before_array_assignments_equals`, `after_array_assignments_equals`, `before_array_assignments_colon` and `after_array_assignments_colon` instead.')
                     ->getOption(),
                 (new FixerOptionBuilder('before_array_assignments_equals', 'Whether to add, remove or ignore spaces before array `=` assignment operator.'))
                     ->setAllowedTypes(['null', 'bool'])

src/Fixer/LanguageConstruct/IsNullFixer.php

@@ -67,21 +67,6 @@ final class IsNullFixer extends AbstractFixer implements ConfigurationDefinition
         return true;
     }
 
-    /**
-     * {@inheritdoc}
-     */
-    public function configure(array $configuration = null)
-    {
-        if (null !== $configuration && array_key_exists('use_yoda_style', $configuration)) {
-            @trigger_error(
-                'Using "use_yoda_style" is deprecated and will be removed in 3.0. Use "yoda_style" fixer instead.',
-                E_USER_DEPRECATED
-            );
-        }
-
-        parent::configure($configuration);
-    }
-
     /**
      * {@inheritdoc}
      */
@@ -212,9 +197,10 @@ final class IsNullFixer extends AbstractFixer implements ConfigurationDefinition
     {
         // @todo 3.0 drop `ConfigurationDefinitionFixerInterface`
         return new FixerConfigurationResolver([
-            (new FixerOptionBuilder('use_yoda_style', '(deprecated) Whether Yoda style conditions should be used.'))
+            (new FixerOptionBuilder('use_yoda_style', 'Whether Yoda style conditions should be used.'))
                 ->setAllowedTypes(['bool'])
                 ->setDefault(true)
+                ->setDeprecationMessage('Use `yoda_style` fixer instead.')
                 ->getOption(),
         ]);
     }

src/Fixer/Operator/BinaryOperatorSpacesFixer.php

@@ -298,13 +298,15 @@ $h = $i===  $j;
                 ->setDefault([])
                 ->getOption(),
             // add deprecated options as BC layer
-            (new FixerOptionBuilder('align_double_arrow', '(deprecated) Whether to apply, remove or ignore double arrows alignment.'))
+            (new FixerOptionBuilder('align_double_arrow', 'Whether to apply, remove or ignore double arrows alignment.'))
                 ->setDefault(false)
                 ->setAllowedValues([true, false, null])
+                ->setDeprecationMessage('Use options `operators` and `default` instead.')
                 ->getOption(),
-            (new FixerOptionBuilder('align_equals', '(deprecated) Whether to apply, remove or ignore equals alignment.'))
+            (new FixerOptionBuilder('align_equals', 'Whether to apply, remove or ignore equals alignment.'))
                 ->setDefault(false)
                 ->setAllowedValues([true, false, null])
+                ->setDeprecationMessage('Use options `operators` and `default` instead.')
                 ->getOption(),
         ]);
     }

src/Fixer/PhpUnit/PhpUnitDedicateAssertFixer.php

@@ -67,7 +67,6 @@ final class PhpUnitDedicateAssertFixer extends AbstractFixer implements Configur
         parent::configure($configuration);
 
         if (isset($this->configuration['functions'])) {
-            @trigger_error('Option "functions" is deprecated and will be removed in 3.0, use option "target" instead.', E_USER_DEPRECATED);
             $this->functions = $this->configuration['functions'];
 
             return;
@@ -234,13 +233,14 @@ $this->assertTrue(is_readable($a));
         sort($values);
 
         return new FixerConfigurationResolverRootless('functions', [
-            (new FixerOptionBuilder('functions', '(deprecated, use `target` instead) List of assertions to fix (overrides `target`).'))
+            (new FixerOptionBuilder('functions', 'List of assertions to fix (overrides `target`).'))
                 ->setAllowedTypes(['null', 'array'])
                 ->setAllowedValues([
                     null,
                     (new FixerOptionValidatorGenerator())->allowedValueIsSubsetOf($values),
                 ])
                 ->setDefault(null)
+                ->setDeprecationMessage('Use option `target` instead.')
                 ->getOption(),
             (new FixerOptionBuilder('target', 'Target version of PHPUnit.'))
                 ->setAllowedTypes(['string'])

src/FixerConfiguration/DeprecatedFixerOption.php

@@ -0,0 +1,100 @@
+<?php
+
+/*
+ * This file is part of PHP CS Fixer.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *     Dariusz Rumiński <dariusz.ruminski@gmail.com>
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+namespace PhpCsFixer\FixerConfiguration;
+
+final class DeprecatedFixerOption implements DeprecatedFixerOptionInterface
+{
+    /**
+     * @var FixerOptionInterface
+     */
+    private $option;
+
+    /**
+     * @var string
+     */
+    private $deprecationMessage;
+
+    /**
+     * @param FixerOptionInterface $option
+     * @param string               $deprecationMessage
+     */
+    public function __construct(FixerOptionInterface $option, $deprecationMessage)
+    {
+        $this->option = $option;
+        $this->deprecationMessage = $deprecationMessage;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getName()
+    {
+        return $this->option->getName();
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getDescription()
+    {
+        return $this->option->getDescription();
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function hasDefault()
+    {
+        return $this->option->hasDefault();
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getDefault()
+    {
+        return $this->option->getDefault();
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getAllowedTypes()
+    {
+        return $this->option->getAllowedTypes();
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getAllowedValues()
+    {
+        return $this->option->getAllowedValues();
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getNormalizer()
+    {
+        return $this->option->getNormalizer();
+    }
+
+    /**
+     * @return string
+     */
+    public function getDeprecationMessage()
+    {
+        return $this->deprecationMessage;
+    }
+}

src/FixerConfiguration/DeprecatedFixerOptionInterface.php

@@ -0,0 +1,21 @@
+<?php
+
+/*
+ * This file is part of PHP CS Fixer.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *     Dariusz Rumiński <dariusz.ruminski@gmail.com>
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+namespace PhpCsFixer\FixerConfiguration;
+
+interface DeprecatedFixerOptionInterface extends FixerOptionInterface
+{
+    /**
+     * @return string
+     */
+    public function getDeprecationMessage();
+}