Deprecate using ~ with + or - in an expression without using parentheses to clarify precedence

CHANGELOG

@@ -1,5 +1,6 @@
 # 3.15.0 (2024-XX-XX)
 
+ * Deprecate using `~` with `+` or `-` in an expression without using parentheses to clarify precedence
  * Deprecate not passing `AbstractExpression` args to most constructor arguments for classes extending `AbstractExpression`
  * Fix `power` expressions with a negative number in parenthesis (`(-1) ** 2`)
  * Deprecate instantiating `Node` directly. Use `EmptyNode` or `Nodes` instead.

doc/deprecated.rst

@@ -310,3 +310,24 @@ Node
   * ``DefaultFilter``
   * ``InlinePrint``
   * ``NullCoalesceExpression``
+
+Operators
+---------
+
+* Using ``~`` with ``+`` or ``-`` in an expression without using parentheses to
+  clarify precedence is deprecated as of Twig 3.15 (in Twig 4.0, parentheses
+  won't be needed anymore as ``+`` / ``-`` will have a higher precedence than
+  ``~``).
+
+  For example, the following expression will trigger a deprecation in Twig 3.15::
+
+    {{ '42' ~ 1 + 41 }}
+
+  To avoid the deprecation, wrap the concatenation in parentheses to clarify
+  the precedence::
+
+    {{ ('42' ~ 1) + 41 }} {# this is equivalent to what Twig 3.x does without the parentheses #}
+
+    {# or #}
+
+    {{ '42' ~ (1 + 41) }} {# this is equivalent to what Twig 4.x will do without the parentheses #}

src/ExpressionParser.php

@@ -20,7 +20,9 @@ use Twig\Node\Expression\ArrayExpression;
 use Twig\Node\Expression\ArrowFunctionExpression;
 use Twig\Node\Expression\AssignNameExpression;
 use Twig\Node\Expression\Binary\AbstractBinary;
+use Twig\Node\Expression\Binary\AddBinary;
 use Twig\Node\Expression\Binary\ConcatBinary;
+use Twig\Node\Expression\Binary\SubBinary;
 use Twig\Node\Expression\ConditionalExpression;
 use Twig\Node\Expression\ConstantExpression;
 use Twig\Node\Expression\GetAttrExpression;
@@ -91,6 +93,18 @@ class ExpressionParser
             $token = $this->parser->getCurrentToken();
         }
 
+        if (
+            ($expr instanceof AddBinary || $expr instanceof SubBinary)
+            &&
+            (
+                ($expr->getNode('left') instanceof ConcatBinary && !$expr->getNode('left')->hasExplicitParentheses())
+                ||
+                ($expr->getNode('right') instanceof ConcatBinary && !$expr->getNode('right')->hasExplicitParentheses())
+            )
+        ) {
+            trigger_deprecation('twig/twig', '3.15', \sprintf('As "+" / "-" will have a higher precedence than "~" in Twig 4.0, please add parentheses to keep the current behavior in "%s" at line %d.', $this->parser->getStream()->getSourceContext()->getName(), $token->getLine()));
+        }
+
         if (0 === $precedence) {
             return $this->parseConditionalExpression($expr);
         }

src/Extension/CoreExtension.php

@@ -323,6 +323,7 @@ final class CoreExtension extends AbstractExtension
                 '..' => ['precedence' => 25, 'class' => RangeBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
                 '+' => ['precedence' => 30, 'class' => AddBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
                 '-' => ['precedence' => 30, 'class' => SubBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
+                // Precedence of the ~ operator will change to 27 in Twig 4.0
                 '~' => ['precedence' => 40, 'class' => ConcatBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
                 '*' => ['precedence' => 60, 'class' => MulBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
                 '/' => ['precedence' => 60, 'class' => DivBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],

tests/Fixtures/operators/concat_vs_add_sub.test

@@ -0,0 +1,16 @@
+--TEST--
++/- will have a higher precedence over ~ in Twig 4.0
+--TEMPLATE--
+{{ 1 + 41 }}
+{{ '42==' ~ '42' }}
+{{ '42==' ~ (1 + 41) }}
+{{ '42==' ~ (43 - 1) }}
+{{ ('42' ~ 43) - 1 }}
+--DATA--
+return []
+--EXPECT--
+42
+42==42
+42==42
+42==42
+4242

tests/Fixtures/operators/contat_vs_add_sub.legacy.test

@@ -0,0 +1,13 @@
+--TEST--
++/- will have a higher precedence over ~ in Twig 4.0
+--DEPRECATION--
+Since twig/twig 3.15: As "+" / "-" will have a higher precedence than "~" in Twig 4.0, please add parentheses to keep the current behavior in "index.twig" at line 2.
+Since twig/twig 3.15: As "+" / "-" will have a higher precedence than "~" in Twig 4.0, please add parentheses to keep the current behavior in "index.twig" at line 3.
+--TEMPLATE--
+{{ '42' ~ 1 + 41 }}
+{{ '42' ~ 43 - 1 }}
+--DATA--
+return []
+--EXPECT--
+462
+4242