From 61031d6cfa29c10740dd755a4471d99631fa8a19 Mon Sep 17 00:00:00 2001 From: Fabien Potencier Date: Wed, 13 Dec 2023 13:40:03 +0100 Subject: [PATCH 1/3] Deprecate passing a Template instance in Environment::resolveTemplate() and Template::loadTemplate() --- CHANGELOG | 1 + src/Environment.php | 6 ++++-- src/Template.php | 12 ++++++++++-- 3 files changed, 15 insertions(+), 4 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index f8f073c83..7c6e293b3 100644 --- a/CHANGELOG +++ b/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"; diff --git a/src/Environment.php b/src/Environment.php index ec9c39da5..bcc587f1e 100644 --- a/src/Environment.php +++ b/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 $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) { diff --git a/src/Template.php b/src/Template.php index f31333240..54527c250 100644 --- a/src/Template.php +++ b/src/Template.php @@ -249,16 +249,24 @@ abstract class Template } /** + * @param string|TemplateWrapper|array $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; } From a62581ae5e91351680b43d26b87925def55b5364 Mon Sep 17 00:00:00 2001 From: Fabien Potencier Date: Sun, 14 Apr 2024 10:10:13 +0200 Subject: [PATCH 2/3] Fix typo --- src/Environment.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Environment.php b/src/Environment.php index bcc587f1e..1e13a3c49 100644 --- a/src/Environment.php +++ b/src/Environment.php @@ -440,8 +440,8 @@ 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 * From dbe9456f770217e669bfd41eadc65a760efb3b2f Mon Sep 17 00:00:00 2001 From: Fabien Potencier Date: Sun, 14 Apr 2024 10:15:06 +0200 Subject: [PATCH 3/3] Fix incompatibility with old PHP versions --- CHANGELOG | 2 +- doc/deprecated.rst | 8 ++++++++ src/Environment.php | 7 ++++++- src/Template.php | 2 +- 4 files changed, 16 insertions(+), 3 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index 7c6e293b3..21bf1278b 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,7 +1,7 @@ # 3.9.0 (2024-XX-XX) * Deprecate AbstractNodeVisitor - * Deprecate passing Template to Environment::resolveTemplate() and Template::loadTemplate() + * 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 1e13a3c49..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)); } @@ -448,7 +453,7 @@ class Environment * @throws LoaderError When none of the templates can be found * @throws SyntaxError When an error occurred during compilation */ - public function resolveTemplate(string|TemplateWrapper|Template|array $names): TemplateWrapper + public function resolveTemplate($names): TemplateWrapper { if (!\is_array($names)) { return $this->load($names); diff --git a/src/Template.php b/src/Template.php index 54527c250..f200a610f 100644 --- a/src/Template.php +++ b/src/Template.php @@ -253,7 +253,7 @@ abstract class Template * * @return self|TemplateWrapper */ - protected function loadTemplate(string|TemplateWrapper|self|array $template, $templateName = null, $line = null, $index = null) + protected function loadTemplate($template, $templateName = null, $line = null, $index = null) { try { if (\is_array($template)) {