feature #3943 Deprecate passing a Template instance in Environment::resolveTemplate() and Template::loadTemplate() (fabpot)

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

Discussion
----------

Deprecate passing a Template instance in Environment::resolveTemplate() and Template::loadTemplate()

Commits
-------

dbe9456f Fix incompatibility with old PHP versions
a62581ae Fix typo
61031d6c Deprecate passing a Template instance in Environment::resolveTemplate() and Template::loadTemplate()

CHANGELOG

@@ -1,6 +1,7 @@
 # 3.9.0 (2024-XX-XX)
 
  * Deprecate AbstractNodeVisitor
+ * Deprecate passing Template to Environment::resolveTemplate(), Environment::load(), and Template::loadTemplate()
  * Add a new "yield" mode for output generation;
    Node implementations that use "echo" or "print" should use "yield" instead;
    all Node implementations should be flagged with `#[YieldReady]` once they've been made ready for "yield";

doc/deprecated.rst

@@ -23,3 +23,11 @@ Node Visitors
 
 * The ``Twig\NodeVisitor\AbstractNodeVisitor`` class is deprecated, implement the
   ``Twig\NodeVisitor\NodeVisitorInterface`` interface instead.
+
+Templates
+---------
+
+* Passing ``Twig\\Template`` instances to Twig public API is deprecated (like
+  in ``Environment::resolveTemplate()``, ``Environment::load()``, and
+  ``Template::loadTemplate()``); pass instances of ``Twig\\TemplateWrapper``
+  instead.

src/Environment.php

@@ -327,6 +327,11 @@ class Environment
         if ($name instanceof TemplateWrapper) {
             return $name;
         }
+        if ($name instanceof Template) {
+            trigger_deprecation('twig/twig', '3.9', 'Passing a "%s" instance to "%s" is deprecated.', self::class, __METHOD__);
+
+            return $name;
+        }
 
         return new TemplateWrapper($this, $this->loadTemplate($this->getTemplateClass($name), $name));
     }
@@ -440,10 +445,10 @@ class Environment
     /**
      * Tries to load a template consecutively from an array.
      *
-     * Similar to load() but it also accepts instances of \Twig\Template and
-     * \Twig\TemplateWrapper, and an array of templates where each is tried to be loaded.
+     * Similar to load() but it also accepts instances of \Twig\TemplateWrapper
+     * and an array of templates where each is tried to be loaded.
      *
-     * @param string|TemplateWrapper|array $names A template or an array of templates to try consecutively
+     * @param string|TemplateWrapper|array<string|TemplateWrapper> $names A template or an array of templates to try consecutively
      *
      * @throws LoaderError When none of the templates can be found
      * @throws SyntaxError When an error occurred during compilation
@@ -457,6 +462,8 @@ class Environment
         $count = \count($names);
         foreach ($names as $name) {
             if ($name instanceof Template) {
+                trigger_deprecation('twig/twig', '3.9', 'Passing a "%s" instance to "%s" is deprecated.', Template::class, __METHOD__);
+
                 return new TemplateWrapper($this, $name);
             }
             if ($name instanceof TemplateWrapper) {

src/Template.php

@@ -249,6 +249,8 @@ abstract class Template
     }
 
     /**
+     * @param string|TemplateWrapper|array<string|TemplateWrapper> $template
+     *
      * @return self|TemplateWrapper
      */
     protected function loadTemplate($template, $templateName = null, $line = null, $index = null)
@@ -258,7 +260,13 @@ abstract class Template
                 return $this->env->resolveTemplate($template);
             }
 
-            if ($template instanceof self || $template instanceof TemplateWrapper) {
+            if ($template instanceof TemplateWrapper) {
+                return $template;
+            }
+
+            if ($template instanceof self) {
+                trigger_deprecation('twig/twig', '3.9', 'Passing a "%s" instance to "%s" is deprecated.', self::class, __METHOD__);
+
                 return $template;
             }