Deprecate Environment::mergeGlobals()

CHANGELOG

@@ -1,6 +1,6 @@
 # 3.13.1 (2024-XX-XX)
 
- * n/a
+ * Deprecate `Environment::mergeGlobals()`
 
 # 3.13.0 (2024-09-07)
 

doc/deprecated.rst

@@ -223,3 +223,17 @@ Testing Utilities
 
 * The data providers ``getTests()`` and ``getLegacyTests()`` on
   ``Twig\Test\IntegrationTestCase`` are considered final als of Twig 3.13.
+
+Environment
+-----------
+
+* The ``Twig\Environment::mergeGlobals()`` method is deprecated as of Twig 3.13
+  and will be removed in Twig 4.0:
+
+  Before::
+
+      $context = $twig->mergeGlobals($context);
+
+  After::
+
+      $context += $twig->getGlobals();

src/Environment.php

@@ -830,17 +830,14 @@ class Environment
         return array_merge($this->extensionSet->getGlobals(), $this->globals);
     }
 
+    /**
+     * @deprecated since Twig 3.13
+     */
     public function mergeGlobals(array $context): array
     {
-        // we don't use array_merge as the context being generally
-        // bigger than globals, this code is faster.
-        foreach ($this->getGlobals() as $key => $value) {
-            if (!\array_key_exists($key, $context)) {
-                $context[$key] = $value;
-            }
-        }
+        trigger_deprecation('twig/twig', '3.13', 'The "%s" method is deprecated.', __METHOD__);
 
-        return $context;
+        return $context + $this->getGlobals();
     }
 
     /**

src/Node/MacroNode.php

@@ -73,7 +73,7 @@ class MacroNode extends Node
             ->write("{\n")
             ->indent()
             ->write("\$macros = \$this->macros;\n")
-            ->write("\$context = \$this->env->mergeGlobals([\n")
+            ->write("\$context = [\n")
             ->indent()
         ;
 
@@ -94,7 +94,7 @@ class MacroNode extends Node
             ->raw(' => ')
             ->raw("\$__varargs__,\n")
             ->outdent()
-            ->write("]);\n\n")
+            ->write("] + \$this->env->getGlobals();\n\n")
             ->write("\$blocks = [];\n\n")
             ->write('return ')
             ->subcompile($node)

src/Node/WithNode.php

@@ -61,7 +61,7 @@ class WithNode extends Node
                 $compiler->write("\$context = [];\n");
             }
 
-            $compiler->write(\sprintf("\$context = \$this->env->mergeGlobals(array_merge(\$context, \$%s));\n", $varsName));
+            $compiler->write(\sprintf("\$context = \$%s + \$context + \$this->env->getGlobals();\n", $varsName));
         }
 
         $compiler

src/Template.php

@@ -386,7 +386,7 @@ abstract class Template
      */
     public function yield(array $context, array $blocks = []): iterable
     {
-        $context = $this->env->mergeGlobals($context);
+        $context += $this->env->getGlobals();
         $blocks = array_merge($this->blocks, $blocks);
 
         try {

src/TemplateWrapper.php

@@ -57,12 +57,12 @@ final class TemplateWrapper
 
     public function renderBlock(string $name, array $context = []): string
     {
-        return $this->template->renderBlock($name, $this->env->mergeGlobals($context));
+        return $this->template->renderBlock($name, $context + $this->env->getGlobals());
     }
 
     public function displayBlock(string $name, array $context = [])
     {
-        $context = $this->env->mergeGlobals($context);
+        $context += $this->env->getGlobals();
         foreach ($this->template->yieldBlock($name, $context) as $data) {
             echo $data;
         }

tests/Node/MacroTest.php

@@ -49,11 +49,11 @@ class MacroTest extends NodeTestCase
 public function macro_foo(\$__foo__ = null, \$__bar__ = "Foo", ...\$__varargs__)
 {
     \$macros = \$this->macros;
-    \$context = \$this->env->mergeGlobals([
+    \$context = [
         "foo" => \$__foo__,
         "bar" => \$__bar__,
         "varargs" => \$__varargs__,
-    ]);
+    ] + \$this->env->getGlobals();
 
     \$blocks = [];
 
@@ -71,11 +71,11 @@ EOF
 public function macro_foo(\$__foo__ = null, \$__bar__ = "Foo", ...\$__varargs__)
 {
     \$macros = \$this->macros;
-    \$context = \$this->env->mergeGlobals([
+    \$context = [
         "foo" => \$__foo__,
         "bar" => \$__bar__,
         "varargs" => \$__varargs__,
-    ]);
+    ] + \$this->env->getGlobals();
 
     \$blocks = [];