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() 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";

src/Environment.php

@@ -443,12 +443,12 @@ class Environment
      * 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.
      *
-     * @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
      */
-    public function resolveTemplate($names): TemplateWrapper
+    public function resolveTemplate(string|TemplateWrapper|Template|array $names): TemplateWrapper
     {
         if (!\is_array($names)) {
             return $this->load($names);
@@ -457,6 +457,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,16 +249,24 @@ abstract class Template
     }
 
     /**
+     * @param string|TemplateWrapper|array<string|TemplateWrapper> $template
+     *
      * @return self|TemplateWrapper
      */
-    protected function loadTemplate($template, $templateName = null, $line = null, $index = null)
+    protected function loadTemplate(string|TemplateWrapper|self|array $template, $templateName = null, $line = null, $index = null)
     {
         try {
             if (\is_array($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;
             }