Merge branch 'master' into docs_docker2

dev-tools/install.sh

@@ -19,13 +19,13 @@ cd "$(dirname "$0")"
 
 mkdir -p bin
 
-VERSION_CB="2.23.6"
+VERSION_CB="2.23.7"
 VERSION_SC="stable"
 
 echo λλλ checkbashisms
 if [ ! -x bin/checkbashisms ]; then
     wget -qO- "https://deb.debian.org/debian/pool/main/d/devscripts/devscripts_${VERSION_CB}.tar.xz" \
-        | tar -xJv -O "devscripts-${VERSION_CB}/scripts/checkbashisms.pl" \
+        | tar -xJv -O "devscripts/scripts/checkbashisms.pl" \
         > bin/checkbashisms
     chmod u+x bin/checkbashisms
 fi

dev-tools/phpstan/baseline.php

@@ -62,7 +62,7 @@
 	'path' => __DIR__ . '/../../src/Doctrine/Annotation/Tokens.php',
 ];
 $ignoreErrors[] = [
-	'message' => '#^Parameter \\#1 \\$array \\(array\\<PhpCsFixer\\\\Doctrine\\\\Annotation\\\\Token\\>\\) of method PhpCsFixer\\\\Doctrine\\\\Annotation\\\\Tokens\\:\\:fromArray\\(\\) should be contravariant with parameter \\$array \\(array\\<int, mixed\\>\\) of method SplFixedArray\\<PhpCsFixer\\\\Doctrine\\\\Annotation\\\\Token\\>\\:\\:fromArray\\(\\)$#',
+	'message' => '#^Parameter \\#1 \\$array \\(array\\<int, PhpCsFixer\\\\Doctrine\\\\Annotation\\\\Token\\>\\) of method PhpCsFixer\\\\Doctrine\\\\Annotation\\\\Tokens\\:\\:fromArray\\(\\) should be contravariant with parameter \\$array \\(array\\<int, mixed\\>\\) of method SplFixedArray\\<PhpCsFixer\\\\Doctrine\\\\Annotation\\\\Token\\>\\:\\:fromArray\\(\\)$#',
 	'count' => 1,
 	'path' => __DIR__ . '/../../src/Doctrine/Annotation/Tokens.php',
 ];

doc/ruleSets/PhpCsFixer.rst

@@ -17,7 +17,6 @@ Rules
 - `combine_consecutive_issets <./../rules/language_construct/combine_consecutive_issets.rst>`_
 - `combine_consecutive_unsets <./../rules/language_construct/combine_consecutive_unsets.rst>`_
 - `empty_loop_body <./../rules/control_structure/empty_loop_body.rst>`_
-- `escape_implicit_backslashes <./../rules/string_notation/escape_implicit_backslashes.rst>`_
 - `explicit_indirect_variable <./../rules/language_construct/explicit_indirect_variable.rst>`_
 - `explicit_string_variable <./../rules/string_notation/explicit_string_variable.rst>`_
 - `fully_qualified_strict_types <./../rules/import/fully_qualified_strict_types.rst>`_ with config:
@@ -68,6 +67,10 @@ Rules
 - `self_static_accessor <./../rules/class_notation/self_static_accessor.rst>`_
 - `single_line_comment_style <./../rules/comment/single_line_comment_style.rst>`_
 - `single_line_empty_body <./../rules/basic/single_line_empty_body.rst>`_
+- `string_implicit_backslashes <./../rules/string_notation/string_implicit_backslashes.rst>`_ with config:
+
+  ``['single_quoted' => 'ignore']``
+
 - `whitespace_after_comma_in_array <./../rules/array_notation/whitespace_after_comma_in_array.rst>`_ with config:
 
   ``['ensure_single_space' => true]``

doc/ruleSets/Symfony.rst

@@ -99,10 +99,7 @@ Rules
 - `no_useless_nullsafe_operator <./../rules/operator/no_useless_nullsafe_operator.rst>`_
 - `no_whitespace_before_comma_in_array <./../rules/array_notation/no_whitespace_before_comma_in_array.rst>`_
 - `normalize_index_brace <./../rules/array_notation/normalize_index_brace.rst>`_
-- `nullable_type_declaration_for_default_null_value <./../rules/function_notation/nullable_type_declaration_for_default_null_value.rst>`_ with config:
-
-  ``['use_nullable_type_declaration' => false]``
-
+- `nullable_type_declaration_for_default_null_value <./../rules/function_notation/nullable_type_declaration_for_default_null_value.rst>`_
 - `object_operator_without_whitespace <./../rules/operator/object_operator_without_whitespace.rst>`_
 - `operator_linebreak <./../rules/operator/operator_linebreak.rst>`_ with config:
 

doc/rules/function_notation/nullable_type_declaration_for_default_null_value.rst

@@ -115,10 +115,7 @@ Rule sets
 
 The rule is part of the following rule set:
 
-- `@Symfony <./../../ruleSets/Symfony.rst>`_ with config:
-
-  ``['use_nullable_type_declaration' => false]``
-
+- `@Symfony <./../../ruleSets/Symfony.rst>`_
 
 References
 ----------

doc/rules/index.rst

@@ -852,7 +852,7 @@ Strict
 String Notation
 ---------------
 
-- `escape_implicit_backslashes <./string_notation/escape_implicit_backslashes.rst>`_
+- `escape_implicit_backslashes <./string_notation/escape_implicit_backslashes.rst>`_ *(deprecated)*
 
   Escape implicit backslashes in strings and heredocs to ease the understanding of which are special chars interpreted by PHP and which not.
 - `explicit_string_variable <./string_notation/explicit_string_variable.rst>`_
@@ -879,6 +879,9 @@ String Notation
 - `single_quote <./string_notation/single_quote.rst>`_
 
   Convert double quotes to single quotes for simple strings.
+- `string_implicit_backslashes <./string_notation/string_implicit_backslashes.rst>`_
+
+  Handles implicit backslashes in strings and heredocs. Depending on the chosen strategy, it can escape implicit backslashes to ease the understanding of which are special chars interpreted by PHP and which not (``escape``), or it can remove these additional backslashes if you find them superfluous (``unescape``). You can also leave them as-is using ``ignore`` strategy.
 - `string_length_to_empty <./string_notation/string_length_to_empty.rst>`_ *(risky)*
 
   String tests for empty must be done against ``''``, not with ``strlen``.

doc/rules/string_notation/escape_implicit_backslashes.rst

@@ -20,6 +20,14 @@ ensure that all backslashes are escaped. Both single and double backslashes are
 allowed in single-quoted strings, so the purpose in this context is mainly to
 have a uniformed way to have them written all over the codebase.
 
+Warning
+-------
+
+This rule is deprecated and will be removed in the next major version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You should use ``string_implicit_backslashes`` instead.
+
 Configuration
 -------------
 
@@ -135,14 +143,6 @@ With configuration: ``['heredoc_syntax' => false]``.
     $hereDoc = <<<HEREDOC
     Interpret my \100 but not my \999
     HEREDOC;
-
-Rule sets
----------
-
-The rule is part of the following rule set:
-
-- `@PhpCsFixer <./../../ruleSets/PhpCsFixer.rst>`_
-
 References
 ----------
 

doc/rules/string_notation/string_implicit_backslashes.rst

@@ -0,0 +1,158 @@
+====================================
+Rule ``string_implicit_backslashes``
+====================================
+
+Handles implicit backslashes in strings and heredocs. Depending on the chosen
+strategy, it can escape implicit backslashes to ease the understanding of which
+are special chars interpreted by PHP and which not (``escape``), or it can
+remove these additional backslashes if you find them superfluous (``unescape``).
+You can also leave them as-is using ``ignore`` strategy.
+
+Description
+-----------
+
+In PHP double-quoted strings and heredocs some chars like ``n``, ``$`` or ``u``
+have special meanings if preceded by a backslash (and some are special only if
+followed by other special chars), while a backslash preceding other chars are
+interpreted like a plain backslash. The precise list of those special chars is
+hard to remember and to identify quickly: this fixer escapes backslashes that do
+not start a special interpretation with the char after them.
+It is possible to fix also single-quoted strings: in this case there is no
+special chars apart from single-quote and backslash itself, so the fixer simply
+ensure that all backslashes are escaped. Both single and double backslashes are
+allowed in single-quoted strings, so the purpose in this context is mainly to
+have a uniformed way to have them written all over the codebase.
+
+Configuration
+-------------
+
+``double_quoted``
+~~~~~~~~~~~~~~~~~
+
+Whether to escape backslashes in double-quoted strings.
+
+Allowed values: ``'escape'``, ``'ignore'`` and ``'unescape'``
+
+Default value: ``'escape'``
+
+``heredoc``
+~~~~~~~~~~~
+
+Whether to escape backslashes in heredoc syntax.
+
+Allowed values: ``'escape'``, ``'ignore'`` and ``'unescape'``
+
+Default value: ``'escape'``
+
+``single_quoted``
+~~~~~~~~~~~~~~~~~
+
+Whether to escape backslashes in single-quoted strings.
+
+Allowed values: ``'escape'``, ``'ignore'`` and ``'unescape'``
+
+Default value: ``'unescape'``
+
+Examples
+--------
+
+Example #1
+~~~~~~~~~~
+
+*Default* configuration.
+
+.. code-block:: diff
+
+   --- Original
+   +++ New
+    <?php
+
+    $singleQuoted = 'String with \" and My\Prefix\\';
+
+   -$doubleQuoted = "Interpret my \n but not my \a";
+   +$doubleQuoted = "Interpret my \n but not my \\a";
+
+    $hereDoc = <<<HEREDOC
+   -Interpret my \100 but not my \999
+   +Interpret my \100 but not my \\999
+    HEREDOC;
+
+Example #2
+~~~~~~~~~~
+
+With configuration: ``['single_quoted' => 'escape']``.
+
+.. code-block:: diff
+
+   --- Original
+   +++ New
+    <?php
+
+   -$singleQuoted = 'String with \" and My\Prefix\\';
+   +$singleQuoted = 'String with \\" and My\\Prefix\\';
+
+   -$doubleQuoted = "Interpret my \n but not my \a";
+   +$doubleQuoted = "Interpret my \n but not my \\a";
+
+    $hereDoc = <<<HEREDOC
+   -Interpret my \100 but not my \999
+   +Interpret my \100 but not my \\999
+    HEREDOC;
+
+Example #3
+~~~~~~~~~~
+
+With configuration: ``['double_quoted' => 'unescape']``.
+
+.. code-block:: diff
+
+   --- Original
+   +++ New
+    <?php
+
+    $singleQuoted = 'String with \" and My\Prefix\\';
+
+    $doubleQuoted = "Interpret my \n but not my \a";
+
+    $hereDoc = <<<HEREDOC
+   -Interpret my \100 but not my \999
+   +Interpret my \100 but not my \\999
+    HEREDOC;
+
+Example #4
+~~~~~~~~~~
+
+With configuration: ``['heredoc' => 'unescape']``.
+
+.. code-block:: diff
+
+   --- Original
+   +++ New
+    <?php
+
+    $singleQuoted = 'String with \" and My\Prefix\\';
+
+   -$doubleQuoted = "Interpret my \n but not my \a";
+   +$doubleQuoted = "Interpret my \n but not my \\a";
+
+    $hereDoc = <<<HEREDOC
+    Interpret my \100 but not my \999
+    HEREDOC;
+
+Rule sets
+---------
+
+The rule is part of the following rule set:
+
+- `@PhpCsFixer <./../../ruleSets/PhpCsFixer.rst>`_ with config:
+
+  ``['single_quoted' => 'ignore']``
+
+
+References
+----------
+
+- Fixer class: `PhpCsFixer\\Fixer\\StringNotation\\StringImplicitBackslashesFixer <./../../../src/Fixer/StringNotation/StringImplicitBackslashesFixer.php>`_
+- Test class: `PhpCsFixer\\Tests\\Fixer\\StringNotation\\StringImplicitBackslashesFixerTest <./../../../tests/Fixer/StringNotation/StringImplicitBackslashesFixerTest.php>`_
+
+The test class defines officially supported behaviour. Each test case is a part of our backward compatibility promise.

src/Console/Command/DescribeCommand.php

@@ -164,8 +164,11 @@ private function describeRule(OutputInterface $output, string $name): void
         if ($fixer instanceof DeprecatedFixerInterface) {
             $successors = $fixer->getSuccessorsNames();
             $message = [] === $successors
-                ? 'will be removed in the next major version'
+                ? sprintf('it will be removed in version %d.0', Application::getMajorVersion() + 1)
                 : sprintf('use %s instead', Utils::naturalLanguageJoinWithBackticks($successors));
+
+            $endMessage = '. '.ucfirst($message);
+            Utils::triggerDeprecation(new \RuntimeException(str_replace('`', '"', "Rule \"{$name}\" is deprecated{$endMessage}.")));
             $message = Preg::replace('/(`[^`]+`)/', '<info>$1</info>', $message);
             $output->writeln(sprintf('<error>DEPRECATED</error>: %s.', $message));
             $output->writeln('');

src/Console/ConfigurationResolver.php

@@ -630,7 +630,7 @@ private function iterableToTraversable(iterable $iterable): \Traversable
     }
 
     /**
-     * @return array<mixed>
+     * @return array<string, mixed>
      */
     private function parseRules(): array
     {
@@ -673,7 +673,7 @@ private function parseRules(): array
     }
 
     /**
-     * @param array<mixed> $rules
+     * @param array<string, mixed> $rules
      *
      * @throws InvalidConfigurationException
      */

src/DocBlock/TypeExpression.php

@@ -241,7 +241,7 @@ public function getTypesGlue(): string
      */
     public function walkTypes(\Closure $callback): void
     {
-        foreach ($this->innerTypeExpressions as [
+        foreach (array_reverse($this->innerTypeExpressions) as [
             'start_index' => $startIndex,
             'expression' => $inner,
         ]) {

src/Doctrine/Annotation/Tokens.php

@@ -138,8 +138,8 @@ public static function createFromDocComment(PhpToken $input, array $ignoredTags
     /**
      * Create token collection from array.
      *
-     * @param Token[] $array       the array to import
-     * @param ?bool   $saveIndices save the numeric indices used in the original array, default is yes
+     * @param array<int, Token> $array       the array to import
+     * @param ?bool             $saveIndices save the numeric indices used in the original array, default is yes
      */
     public static function fromArray($array, $saveIndices = null): self
     {

src/Fixer/Alias/BacktickToShellExecFixer.php

@@ -53,7 +53,7 @@ public function getDefinition(): FixerDefinitionInterface
     /**
      * {@inheritdoc}
      *
-     * Must run before EscapeImplicitBackslashesFixer, ExplicitStringVariableFixer, NativeFunctionInvocationFixer, SingleQuoteFixer.
+     * Must run before EscapeImplicitBackslashesFixer, ExplicitStringVariableFixer, NativeFunctionInvocationFixer, SingleQuoteFixer, StringImplicitBackslashesFixer.
      */
     public function getPriority(): int
     {

src/Fixer/Casing/LowercaseStaticReferenceFixer.php

@@ -84,7 +84,7 @@ protected function applyFix(\SplFileInfo $file, Tokens $tokens): void
             }
 
             $prevIndex = $tokens->getPrevMeaningfulToken($index);
-            if ($tokens[$prevIndex]->isGivenKind([T_CONST, T_DOUBLE_COLON, T_FUNCTION, T_NAMESPACE, T_NS_SEPARATOR]) || $tokens[$prevIndex]->isObjectOperator()) {
+            if ($tokens[$prevIndex]->isGivenKind([T_CONST, T_DOUBLE_COLON, T_FUNCTION, T_NAMESPACE, T_NS_SEPARATOR, T_STATIC, T_STRING, CT::T_ARRAY_TYPEHINT, CT::T_DISJUNCTIVE_NORMAL_FORM_TYPE_PARENTHESIS_CLOSE]) || $tokens[$prevIndex]->isObjectOperator()) {
                 continue;
             }
 

src/Fixer/ClassNotation/ClassDefinitionFixer.php

@@ -23,6 +23,7 @@
 use PhpCsFixer\FixerDefinition\CodeSample;
 use PhpCsFixer\FixerDefinition\FixerDefinition;
 use PhpCsFixer\FixerDefinition\FixerDefinitionInterface;
+use PhpCsFixer\Tokenizer\CT;
 use PhpCsFixer\Tokenizer\Token;
 use PhpCsFixer\Tokenizer\Tokens;
 use PhpCsFixer\Tokenizer\TokensAnalyzer;
@@ -362,15 +363,37 @@ private function makeClassyDefinitionSingleLine(Tokens $tokens, int $startIndex,
     {
         for ($i = $endIndex; $i >= $startIndex; --$i) {
             if ($tokens[$i]->isWhitespace()) {
-                if ($tokens[$i - 1]->isComment() || $tokens[$i + 1]->isComment()) {
+                if (str_contains($tokens[$i]->getContent(), "\n")) {
+                    if (\defined('T_ATTRIBUTE')) { // @TODO: drop condition and else when PHP 8.0+ is required
+                        if ($tokens[$i - 1]->isGivenKind(CT::T_ATTRIBUTE_CLOSE) || $tokens[$i + 1]->isGivenKind(T_ATTRIBUTE)) {
+                            continue;
+                        }
+                    } else {
+                        if (($tokens[$i - 1]->isComment() && str_ends_with($tokens[$i - 1]->getContent(), ']'))
+                            || ($tokens[$i + 1]->isComment() && str_starts_with($tokens[$i + 1]->getContent(), '#['))
+                        ) {
+                            continue;
+                        }
+                    }
+
+                    if ($tokens[$i - 1]->isGivenKind(T_DOC_COMMENT) || $tokens[$i + 1]->isGivenKind(T_DOC_COMMENT)) {
+                        continue;
+                    }
+                }
+
+                if ($tokens[$i - 1]->isComment()) {
                     $content = $tokens[$i - 1]->getContent();
+                    if (!str_starts_with($content, '//') && !str_starts_with($content, '#')) {
+                        $tokens[$i] = new Token([T_WHITESPACE, ' ']);
+                    }
 
-                    if (!('#' === $content || str_starts_with($content, '//'))) {
-                        $content = $tokens[$i + 1]->getContent();
+                    continue;
+                }
 
-                        if (!('#' === $content || str_starts_with($content, '//'))) {
-                            $tokens[$i] = new Token([T_WHITESPACE, ' ']);
-                        }
+                if ($tokens[$i + 1]->isComment()) {
+                    $content = $tokens[$i + 1]->getContent();
+                    if (!str_starts_with($content, '//')) {
+                        $tokens[$i] = new Token([T_WHITESPACE, ' ']);
                     }
 
                     continue;