diff --git a/CHANGELOG b/CHANGELOG index f8f073c83..21bf1278b 100644 --- a/CHANGELOG +++ b/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"; diff --git a/doc/deprecated.rst b/doc/deprecated.rst index b4cdf774d..4121d1905 100644 --- a/doc/deprecated.rst +++ b/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. diff --git a/src/Environment.php b/src/Environment.php index ec9c39da5..3422ca49f 100644 --- a/src/Environment.php +++ b/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 $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) { diff --git a/src/Template.php b/src/Template.php index f31333240..f200a610f 100644 --- a/src/Template.php +++ b/src/Template.php @@ -249,6 +249,8 @@ abstract class Template } /** + * @param string|TemplateWrapper|array $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; }