feature twigphp#4055 Extract the escaping logic to a runtime (fabpot)

This PR was squashed before being merged into the 3.x branch.

Discussion
----------

Extract the escaping logic to a runtime

Commits
-------

ead768a -
e4a7853 Add missing `@deprecated` tags
d728d1b Add more information about migrating away from twig_escape_filter()
70b2e3c Fix compat with older versions of PHP
84bff06 Extract the escaping logic to a runtime

CHANGELOG

@@ -1,6 +1,12 @@
-# 3.9.4 (2024-XX-XX)
+# 3.10.0 (2024-XX-XX)
 
- * n/a
+ * Extract the escaping logic from the `EscapingExtension` class to a new
+   `EscapingRuntime` class.
+
+   The following methods from ``Twig\\Extension\\EscaperExtension`` are
+   deprecated: ``setEscaper()``, ``getEscapers()``, ``setDefaultStrategy()``,
+   ``getDefaultStrategy()``, ``setSafeClasses``, ``addSafeClasses()``. Use the
+   same methods on the ``Twig\\Runtime\\EscaperRuntime`` class instead.
 
 # 3.9.3 (2024-04-18)
 

doc/deprecated.rst

@@ -18,6 +18,20 @@ Extensions
   3.9.0, and will be removed in Twig 4.0. They have been replaced by internal
   methods on their respective extension classes.
 
+  If you were using the ``twig_escape_filter()`` function in your code, use
+  ``$env->getRuntime(EscaperRuntime::class)->escape()`` instead.
+
+* The following methods from ``Twig\Extension\EscaperExtension`` are
+  deprecated: ``setEscaper()``, ``getEscapers()``, ``setDefaultStrategy()``,
+  ``getDefaultStrategy()``, ``setSafeClasses``, ``addSafeClasses()``. Use the
+  same methods on the ``Twig\Runtime\EscaperRuntime`` class instead.
+
+  Before:
+  $twig->getExtension(EscaperExtension::class)->METHOD()
+
+  After:
+  $twig->getRuntime(EscaperRuntime::class)->METHOD();
+
 Node Visitors
 -------------
 

src/Environment.php

@@ -31,6 +31,8 @@
 use Twig\Node\ModuleNode;
 use Twig\Node\Node;
 use Twig\NodeVisitor\NodeVisitorInterface;
+use Twig\Runtime\EscaperRuntime;
+use Twig\RuntimeLoader\FactoryRuntimeLoader;
 use Twig\RuntimeLoader\RuntimeLoaderInterface;
 use Twig\TokenParser\TokenParserInterface;
 
@@ -41,11 +43,11 @@
  */
 class Environment
 {
-    public const VERSION = '3.9.4-DEV';
-    public const VERSION_ID = 30904;
+    public const VERSION = '3.10.0-DEV';
+    public const VERSION_ID = 301000;
     public const MAJOR_VERSION = 3;
-    public const MINOR_VERSION = 9;
-    public const RELEASE_VERSION = 4;
+    public const MINOR_VERSION = 10;
+    public const RELEASE_VERSION = 0;
     public const EXTRA_VERSION = 'DEV';
 
     private $charset;
@@ -69,6 +71,7 @@ class Environment
     private $optionsHash;
     /** @var bool */
     private $useYield;
+    private $defaultRuntimeLoader;
 
     /**
      * Constructor.
@@ -127,9 +130,12 @@ public function __construct(LoaderInterface $loader, $options = [])
         $this->strictVariables = (bool) $options['strict_variables'];
         $this->setCache($options['cache']);
         $this->extensionSet = new ExtensionSet();
+        $this->defaultRuntimeLoader = new FactoryRuntimeLoader([
+            EscaperRuntime::class => function () use ($options) { return new EscaperRuntime($options['autoescape'], $this->charset); },
+        ]);
 
         $this->addExtension(new CoreExtension());
-        $this->addExtension(new EscaperExtension($options['autoescape']));
+        $this->addExtension(new EscaperExtension($this->getRuntime(EscaperRuntime::class)));
         if (\PHP_VERSION_ID >= 80000) {
             $this->addExtension(new YieldNotReadyExtension($this->useYield));
         }
@@ -620,6 +626,10 @@ public function getRuntime(string $class)
             }
         }
 
+        if (null !== $runtime = $this->defaultRuntimeLoader->load($class)) {
+            return $this->runtimes[$class] = $runtime;
+        }
+
         throw new RuntimeError(sprintf('Unable to load the "%s" runtime.', $class));
     }