Merge branch '2.15' into 2.16

# Conflicts:
#	tests/AutoReview/FixerTest.php

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,7 +1,7 @@
 ---
 name: Bug report 🐛
 about: Existing feature does not behave as expected.
-label: kind/bug
+labels: kind/bug
 ---
 
 ## Bug report

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,7 +1,7 @@
 ---
 name: Feature request 🚀
 about: I have a suggestion about a new feature (and may want to implement it)!
-label: kind/feature request
+labels: kind/feature request
 ---
 
 ## Feature request

.github/ISSUE_TEMPLATE/rule_request.md

@@ -1,7 +1,7 @@
 ---
 name: Rule request ✍️
 about: I have a suggestion about a new rule (and may want to implement it)!
-label: kind/feature request
+labels: kind/feature request
 ---
 
 ## Rule request

.github/ISSUE_TEMPLATE/support_question.md

@@ -1,7 +1,7 @@
 ---
 name: Support question ❓
 about: You have a question about how the tool works or how to use it.
-label: kind/question
+labels: kind/question
 ---
 
 ## Support question

README.rst

@@ -193,14 +193,14 @@ apply (the rule names must be separated by a comma):
 
     $ php php-cs-fixer.phar fix /path/to/dir --rules=line_ending,full_opening_tag,indentation_type
 
-You can also blacklist the rules you don't want by placing a dash in front of the rule name, if this is more convenient,
+You can also exclude the rules you don't want by placing a dash in front of the rule name, if this is more convenient,
 using ``-name_of_fixer``:
 
 .. code-block:: bash
 
     $ php php-cs-fixer.phar fix /path/to/dir --rules=-full_opening_tag,-indentation_type
 
-When using combinations of exact and blacklist rules, applying exact rules along with above blacklisted results:
+When using combinations of exact and exclude rules, applying exact rules along with above excluded results:
 
 .. code-block:: bash
 
@@ -691,8 +691,8 @@ Choose from the list of available rules:
   Configuration options:
 
   - ``annotation-black-list`` (``array``): class level annotations tags that must be
-    omitted to fix the class, even if all of the white list ones are used
-    as well. (case insensitive); defaults to ``['@final', '@Entity',
+    omitted to fix the class, even if all of the excluded ones are used as
+    well. (case insensitive); defaults to ``['@final', '@Entity',
     '@ORM\\Entity', '@ORM\\Mapping\\Entity', '@Mapping\\Entity']``
   - ``annotation-white-list`` (``array``): class level annotations tags that must be
     set in order to fix the class. (case insensitive); defaults to
@@ -2061,7 +2061,7 @@ Both ``exclude`` and ``notPath`` methods accept only relative paths to the ones
 See `Symfony\\Finder <https://symfony.com/doc/current/components/finder.html>`_
 online documentation for other `Finder` methods.
 
-You may also use a blacklist for the rules instead of the above shown whitelist approach.
+You may also use an exclude list for the rules instead of the above shown include approach.
 The following example shows how to use all ``Symfony`` rules but the ``full_opening_tag`` rule.
 
 .. code-block:: php

src/Console/Command/HelpCommand.php

@@ -94,12 +94,12 @@ public static function getHelpCopy()
 
     <info>$ php %command.full_name% /path/to/dir --rules=line_ending,full_opening_tag,indentation_type</info>
 
-You can also blacklist the rules you don't want by placing a dash in front of the rule name, if this is more convenient,
+You can also exclude the rules you don't want by placing a dash in front of the rule name, if this is more convenient,
 using <comment>-name_of_fixer</comment>:
 
     <info>$ php %command.full_name% /path/to/dir --rules=-full_opening_tag,-indentation_type</info>
 
-When using combinations of exact and blacklist rules, applying exact rules along with above blacklisted results:
+When using combinations of exact and exclude rules, applying exact rules along with above excluded results:
 
     <info>$ php %command.full_name% /path/to/project --rules=@Symfony,-@PSR1,-blank_line_before_statement,strict_comparison</info>
 
@@ -203,7 +203,7 @@ public static function getHelpCopy()
 See `Symfony\Finder` (<url>https://symfony.com/doc/current/components/finder.html</url>)
 online documentation for other `Finder` methods.
 
-You may also use a blacklist for the rules instead of the above shown whitelist approach.
+You may also use an exclude list for the rules instead of the above shown include approach.
 The following example shows how to use all ``Symfony`` rules but the ``full_opening_tag`` rule.
 
     <?php

src/Fixer/ClassNotation/ClassAttributesSeparationFixer.php

@@ -106,7 +106,7 @@ class Sample
      * {@inheritdoc}
      *
      * Must run before BracesFixer, IndentationTypeFixer.
-     * Must run after OrderedClassElementsFixer.
+     * Must run after OrderedClassElementsFixer, SingleClassElementPerStatementFixer.
      */
     public function getPriority()
     {

src/Fixer/ClassNotation/FinalInternalClassFixer.php

@@ -44,7 +44,7 @@ public function configure(array $configuration = null)
         );
 
         if (\count($intersect)) {
-            throw new InvalidFixerConfigurationException($this->getName(), sprintf('Annotation cannot be used in both the white- and black list, got duplicates: "%s".', implode('", "', array_keys($intersect))));
+            throw new InvalidFixerConfigurationException($this->getName(), sprintf('Annotation cannot be used in both the include and exclude list, got duplicates: "%s".', implode('", "', array_keys($intersect))));
         }
     }
 
@@ -152,7 +152,7 @@ protected function createConfigurationDefinition()
                 ->setDefault(['@internal'])
                 ->setNormalizer($annotationsNormalizer)
                 ->getOption(),
-            (new FixerOptionBuilder('annotation-black-list', 'Class level annotations tags that must be omitted to fix the class, even if all of the white list ones are used as well. (case insensitive)'))
+            (new FixerOptionBuilder('annotation-black-list', 'Class level annotations tags that must be omitted to fix the class, even if all of the excluded ones are used as well. (case insensitive)'))
                 ->setAllowedTypes(['array'])
                 ->setAllowedValues($annotationsAsserts)
                 ->setDefault([
@@ -196,7 +196,7 @@ private function isClassCandidate(Tokens $tokens, $index)
             $tag = strtolower(substr(array_shift($matches), 1));
             foreach ($this->configuration['annotation-black-list'] as $tagStart => $true) {
                 if (0 === strpos($tag, $tagStart)) {
-                    return false; // ignore class: class-level PHPDoc contains tag that has been black listed through configuration
+                    return false; // ignore class: class-level PHPDoc contains tag that has been excluded through configuration
                 }
             }
 
@@ -205,7 +205,7 @@ private function isClassCandidate(Tokens $tokens, $index)
 
         foreach ($this->configuration['annotation-white-list'] as $tag => $true) {
             if (!isset($tags[$tag])) {
-                return false; // ignore class: class-level PHPDoc does not contain all tags that has been white listed through configuration
+                return false; // ignore class: class-level PHPDoc does not contain all tags that has been included through configuration
             }
         }
 

src/Fixer/ClassNotation/SingleClassElementPerStatementFixer.php

@@ -43,6 +43,16 @@ public function isCandidate(Tokens $tokens)
         return $tokens->isAnyTokenKindsFound(Token::getClassyTokenKinds());
     }
 
+    /**
+     * {@inheritdoc}
+     *
+     * Must run before ClassAttributesSeparationFixer.
+     */
+    public function getPriority()
+    {
+        return 56;
+    }
+
     /**
      * {@inheritdoc}
      */

src/Fixer/Comment/NoEmptyCommentFixer.php

@@ -89,6 +89,11 @@ private function getCommentBlock(Tokens $tokens, $index)
     {
         $commentType = $this->getCommentType($tokens[$index]->getContent());
         $empty = $this->isEmptyComment($tokens[$index]->getContent());
+
+        if (self::TYPE_SLASH_ASTERISK === $commentType) {
+            return [$index, $index, $empty];
+        }
+
         $start = $index;
         $count = \count($tokens);
         ++$index;

src/Fixer/ControlStructure/NoUnneededCurlyBracesFixer.php

@@ -131,9 +131,9 @@ private function findCurlyBraceOpen(Tokens $tokens)
      */
     private function isOverComplete(Tokens $tokens, $index)
     {
-        static $whiteList = ['{', '}', [T_OPEN_TAG], ':', ';'];
+        static $include = ['{', '}', [T_OPEN_TAG], ':', ';'];
 
-        return $tokens[$tokens->getPrevMeaningfulToken($index)]->equalsAny($whiteList);
+        return $tokens[$tokens->getPrevMeaningfulToken($index)]->equalsAny($include);
     }
 
     private function clearIfIsOverCompleteNamespaceBlock(Tokens $tokens)

src/Fixer/DoctrineAnnotation/DoctrineAnnotationSpacesFixer.php

@@ -38,6 +38,10 @@ public function getDefinition()
                 new CodeSample(
                     "<?php\n/**\n * @Foo ( )\n */\nclass Bar {}\n\n/**\n * @Foo(\"bar\" ,\"baz\")\n */\nclass Bar2 {}\n\n/**\n * @Foo(foo = \"foo\", bar = {\"foo\":\"foo\", \"bar\"=\"bar\"})\n */\nclass Bar3 {}\n"
                 ),
+                new CodeSample(
+                    "<?php\n/**\n * @Foo(foo = \"foo\", bar = {\"foo\":\"foo\", \"bar\"=\"bar\"})\n */\nclass Bar {}\n",
+                    ['after_array_assignments_equals' => false, 'before_array_assignments_equals' => false]
+                ),
             ],
             'There must not be any space around parentheses; commas must be preceded by no space and followed by one space; there must be no space around named arguments assignment operator; there must be one space around array assignment operator.'
         );

src/Fixer/FunctionNotation/NativeFunctionInvocationFixer.php

@@ -164,6 +164,7 @@ function baz($options)
      * {@inheritdoc}
      *
      * Must run before GlobalNamespaceImportFixer.
+     * Must run after StrictParamFixer.
      */
     public function getPriority()
     {

src/Fixer/FunctionNotation/PhpdocToReturnTypeFixer.php

@@ -34,7 +34,7 @@ final class PhpdocToReturnTypeFixer extends AbstractFixer implements Configurati
     /**
      * @var array<int, array<int, int|string>>
      */
-    private $blacklistFuncNames = [
+    private $excludeFuncNames = [
         [T_STRING, '__construct'],
         [T_STRING, '__destruct'],
         [T_STRING, '__clone'],
@@ -115,6 +115,16 @@ function my_foo()
 ',
                     new VersionSpecification(70200)
                 ),
+                new VersionSpecificCodeSample(
+                    '<?php
+/** @return Foo */
+function foo() {}
+/** @return string */
+function bar() {}
+',
+                    new VersionSpecification(70100),
+                    ['scalar_types' => false]
+                ),
             ],
             null,
             'This rule is EXPERIMENTAL and [1] is not covered with backward compatibility promise. [2] `@return` annotation is mandatory for the fixer to make changes, signatures of methods without it (no docblock, inheritdocs) will not be fixed. [3] Manual actions are required if inherited signatures are not properly documented. [4] `@inheritdocs` support is under construction.'
@@ -179,7 +189,7 @@ protected function applyFix(\SplFileInfo $file, Tokens $tokens)
             }
 
             $funcName = $tokens->getNextMeaningfulToken($index);
-            if ($tokens[$funcName]->equalsAny($this->blacklistFuncNames, false)) {
+            if ($tokens[$funcName]->equalsAny($this->excludeFuncNames, false)) {
                 continue;
             }
 

src/Fixer/FunctionNotation/VoidReturnFixer.php

@@ -50,6 +50,7 @@ public function getDefinition()
      * {@inheritdoc}
      *
      * Must run before PhpdocNoEmptyReturnFixer, ReturnTypeDeclarationFixer.
+     * Must run after SimplifiedNullReturnFixer.
      */
     public function getPriority()
     {
@@ -78,7 +79,7 @@ public function isRisky()
     protected function applyFix(\SplFileInfo $file, Tokens $tokens)
     {
         // These cause syntax errors.
-        static $blacklistFuncNames = [
+        static $excludeFuncNames = [
             [T_STRING, '__construct'],
             [T_STRING, '__destruct'],
             [T_STRING, '__clone'],
@@ -90,7 +91,7 @@ protected function applyFix(\SplFileInfo $file, Tokens $tokens)
             }
 
             $funcName = $tokens->getNextMeaningfulToken($index);
-            if ($tokens[$funcName]->equalsAny($blacklistFuncNames, false)) {
+            if ($tokens[$funcName]->equalsAny($excludeFuncNames, false)) {
                 continue;
             }
 

src/Fixer/PhpUnit/PhpUnitInternalClassFixer.php

@@ -38,7 +38,13 @@ public function getDefinition()
     {
         return new FixerDefinition(
             'All PHPUnit test classes should be marked as internal.',
-            [new CodeSample("<?php\nclass MyTest extends TestCase {}\n")]
+            [
+                new CodeSample("<?php\nclass MyTest extends TestCase {}\n"),
+                new CodeSample(
+                    "<?php\nclass MyTest extends TestCase {}\nfinal class FinalTest extends TestCase {}\nabstract class AbstractTest extends TestCase {}\n",
+                    ['types' => ['final']]
+                ),
+            ]
         );
     }
 

src/Fixer/PhpUnit/PhpUnitNamespacedFixer.php

@@ -49,16 +49,21 @@ final class PhpUnitNamespacedFixer extends AbstractFixer implements Configuratio
      */
     public function getDefinition()
     {
-        return new FixerDefinition(
-            'PHPUnit classes MUST be used in namespaced version, e.g. `\PHPUnit\Framework\TestCase` instead of `\PHPUnit_Framework_TestCase`.',
-            [
-                new CodeSample(
-                    '<?php
+        $codeSample = '<?php
 final class MyTest extends \PHPUnit_Framework_TestCase
 {
+    public function testSomething()
+    {
+        PHPUnit_Framework_Assert::assertTrue(true);
+    }
 }
-'
-                ),
+';
+
+        return new FixerDefinition(
+            'PHPUnit classes MUST be used in namespaced version, e.g. `\PHPUnit\Framework\TestCase` instead of `\PHPUnit_Framework_TestCase`.',
+            [
+                new CodeSample($codeSample),
+                new CodeSample($codeSample, ['target' => PhpUnitTargetVersion::VERSION_4_8]),
             ],
             "PHPUnit v6 has finally fully switched to namespaces.\n"
             ."You could start preparing the upgrade by switching from non-namespaced TestCase to namespaced one.\n"

src/Fixer/PhpUnit/PhpUnitTestCaseStaticMethodCallsFixer.php

@@ -274,11 +274,7 @@ final class PhpUnitTestCaseStaticMethodCallsFixer extends AbstractFixer implemen
      */
     public function getDefinition()
     {
-        return new FixerDefinition(
-            'Calls to `PHPUnit\Framework\TestCase` static methods must all be of the same type, either `$this->`, `self::` or `static::`.',
-            [
-                new CodeSample(
-                    '<?php
+        $codeSample = '<?php
 final class MyTest extends \PHPUnit_Framework_TestCase
 {
     public function testMe()
@@ -288,8 +284,13 @@ public function testMe()
         static::assertSame(1, 2);
     }
 }
-'
-                ),
+';
+
+        return new FixerDefinition(
+            'Calls to `PHPUnit\Framework\TestCase` static methods must all be of the same type, either `$this->`, `self::` or `static::`.',
+            [
+                new CodeSample($codeSample),
+                new CodeSample($codeSample, ['call_type' => self::CALL_TYPE_THIS]),
             ],
             null,
             'Risky when PHPUnit methods are overridden or not accessible, or when project has PHPUnit incompatibilities.'

src/Fixer/Phpdoc/GeneralPhpdocAnnotationRemoveFixer.php

@@ -40,12 +40,24 @@ public function getDefinition()
                     '<?php
 /**
  * @internal
- * @author someone
+ * @author John Doe
  */
 function foo() {}
 ',
                     ['annotations' => ['author']]
                 ),
+                new CodeSample(
+                    '<?php
+/**
+ * @author John Doe
+ * @package ACME API
+ * @subpackage Authorization
+ * @version 1.0
+ */
+function foo() {}
+',
+                    ['annotations' => ['package', 'subpackage']]
+                ),
             ]
         );
     }

src/Fixer/Phpdoc/PhpdocScalarFixer.php

@@ -46,7 +46,8 @@ public function getDefinition()
     {
         return new FixerDefinition(
             'Scalar types should always be written in the same form. `int` not `integer`, `bool` not `boolean`, `float` not `real` or `double`.',
-            [new CodeSample('<?php
+            [
+                new CodeSample('<?php
 /**
  * @param integer $a
  * @param boolean $b
@@ -58,7 +59,22 @@ function sample($a, $b, $c)
 {
     return sample2($a, $b, $c);
 }
-')]
+'),
+                new CodeSample(
+                    '<?php
+/**
+ * @param integer $a
+ * @param boolean $b
+ * @param real $c
+ */
+function sample($a, $b, $c)
+{
+    return sample2($a, $b, $c);
+}
+',
+                    ['types' => ['boolean']]
+                ),
+            ]
         );
     }