Merge branch '2.19' into 3.0

* 2.19:
  Fix checkbashisms installation
  Fix transforming deprecations into exceptions
  Update LICENSE
  Fix reStructuredText markup

LICENSE

@@ -1,5 +1,4 @@
-Copyright (c) 2012-2021 Fabien Potencier
-                        Dariusz Rumiński
+Copyright (c) 2012-2021 Fabien Potencier, Dariusz Rumiński
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

dev-tools/install.sh

@@ -20,7 +20,7 @@ cd "$(dirname "$0")"
 
 mkdir -p bin
 
-VERSION_CB="2.21.1"
+VERSION_CB="2.21.2"
 VERSION_SC="stable"
 
 echo λλλ checkbashisms

doc/custom_rules.rst

@@ -14,6 +14,7 @@ regarding custom rules names: they must match the pattern
 Then register your custom fixers and enable them in the config file:
 
 .. code-block:: php
+
     <?php
     // ...
     return (new PhpCsFixer\Config())
@@ -28,6 +29,7 @@ Then register your custom fixers and enable them in the config file:
             'YourVendorName/custome_rule_2' => true,
         ])
     ;
+
 There are several interfaces that your fixers can also implement if needed:
 
 * `PhpCsFixer\\Fixer\\WhitespacesAwareFixerInterface <./src/Fixer/WhitespacesAwareFixerInterface.php>`_: for fixers that need to know the configured indentation and line endings;

src/AbstractFixer.php

@@ -124,16 +124,13 @@ abstract class AbstractFixer implements FixerInterface
 
             $name = $option->getName();
             if (\array_key_exists($name, $configuration)) {
-                Utils::triggerDeprecation(
-                    sprintf(
-                        'Option "%s" for rule "%s" is deprecated and will be removed in version %d.0. %s',
-                        $name,
-                        $this->getName(),
-                        Application::getMajorVersion() + 1,
-                        str_replace('`', '"', $option->getDeprecationMessage())
-                    ),
-                    \InvalidArgumentException::class
-                );
+                Utils::triggerDeprecation(new \InvalidArgumentException(sprintf(
+                    'Option "%s" for rule "%s" is deprecated and will be removed in version %d.0. %s',
+                    $name,
+                    $this->getName(),
+                    Application::getMajorVersion() + 1,
+                    str_replace('`', '"', $option->getDeprecationMessage())
+                )));
             }
         }
 

src/Console/ConfigurationResolver.php

@@ -691,7 +691,7 @@ final class ConfigurationResolver
                     ? sprintf(' and will be removed in version %d.0.', Application::getMajorVersion() + 1)
                     : sprintf('. Use %s instead.', str_replace('`', '"', Utils::naturalLanguageJoinWithBackticks($successors)));
 
-                Utils::triggerDeprecation("Rule \"{$fixerName}\" is deprecated{$messageEnd}");
+                Utils::triggerDeprecation(new \RuntimeException("Rule \"{$fixerName}\" is deprecated{$messageEnd}"));
             }
         }
     }

src/FixerConfiguration/FixerConfigurationResolver.php

@@ -70,7 +70,11 @@ final class FixerConfigurationResolver implements FixerConfigurationResolverInte
                         throw new InvalidOptionsException(sprintf('Aliased option "%s"/"%s" is passed multiple times.', $name, $alias));
                     }
 
-                    Utils::triggerDeprecation(sprintf('Option "%s" is deprecated, use "%s" instead.', $alias, $name));
+                    Utils::triggerDeprecation(new \RuntimeException(sprintf(
+                        'Option "%s" is deprecated, use "%s" instead.',
+                        $alias,
+                        $name
+                    )));
 
                     $options[$name] = $options[$alias];
                     unset($options[$alias]);

src/Utils.php

@@ -160,12 +160,18 @@ final class Utils
     /**
      * Handle triggering deprecation error.
      */
-    public static function triggerDeprecation(string $message, string $exceptionClass = \RuntimeException::class): void
+    public static function triggerDeprecation(\Exception $futureException)
     {
         if (getenv('PHP_CS_FIXER_FUTURE_MODE')) {
-            throw new $exceptionClass("{$message} This check was performed as `PHP_CS_FIXER_FUTURE_MODE` env var is set.");
+            throw new \RuntimeException(
+                'Your are using something deprecated, see previous exception. Aborting execution because `PHP_CS_FIXER_FUTURE_MODE` environment variable is set.',
+                0,
+                $futureException
+            );
         }
 
+        $message = $futureException->getMessage();
+
         self::$deprecations[$message] = true;
         @trigger_error($message, E_USER_DEPRECATED);
     }

tests/UtilsTest.php

@@ -269,17 +269,23 @@ final class UtilsTest extends TestCase
 
         $this->expectDeprecation('The message');
 
-        Utils::triggerDeprecation('The message', \DomainException::class);
+        Utils::triggerDeprecation(new \DomainException('The message'));
     }
 
     public function testTriggerDeprecationWhenFutureModeIsOn(): void
     {
         putenv('PHP_CS_FIXER_FUTURE_MODE=1');
 
-        $this->expectException(\DomainException::class);
-        $this->expectExceptionMessage('The message');
+        $exception = new \DomainException('The message');
+        $futureModeException = null;
 
-        Utils::triggerDeprecation('The message', \DomainException::class);
+        try {
+            Utils::triggerDeprecation($exception);
+        } catch (\Exception $futureModeException) {
+        }
+
+        static::assertInstanceOf(\RuntimeException::class, $futureModeException);
+        static::assertSame($exception, $futureModeException->getPrevious());
     }
 
     private function createFixerDouble(string $name, int $priority)