Twig 3移除base_template_class后自定义模板逻辑的替代方案

根据Twig 3.0.0-BETA1版本更新日志，Twig\Environment的base_template_class配置项已正式移除，不再支持通过自定义Twig\Template子类重写display()、render()方法注入逻辑。
针对模板栈记录、模板继承层级计数这类需求，Twig官方推荐的替代方案是自定义节点访问器（Node Visitor）+ 扩展注册，通过在模板编译阶段向对应执行节点注入逻辑，实现和重写基类方法完全一致的效果，Twig官方自带的Profiler、Debug扩展均采用该方案实现渲染追踪、调试能力，兼容性稳定。

具体实现步骤 #

• 自定义节点访问器，在模板编译阶段注入原有业务逻辑
  节点访问器可以在Twig编译模板时遍历所有语法节点，在display、render方法的执行前后插入自定义代码，不需要修改模板基类：

<?php
use Twig\Environment;
use Twig\Node\ModuleNode;
use Twig\Node\Node;
use Twig\NodeVisitor\NodeVisitorInterface;
use Twig\Compiler;

class TemplateTrackNodeVisitor implements NodeVisitorInterface
{
    public function enterNode(Node $node, Environment $env): Node
    {
        if (!$node instanceof ModuleNode) {
            return $node;
        }

        // 向display方法开头注入模板栈记录、层级计数逻辑
        $node->getNode('display_start')->setNode('custom_track_logic', new class extends Node {
            public function compile(Compiler $compiler)
            {
                $compiler
                    ->write('$env = $this->env;' . "\n")
                    ->write('$env->addTemplateStack($this->getTemplateName());' . "\n")
                    ->write('if (is_array($blocks)) {' . "\n")
                    ->indent()
                    ->write('$env->current_inheritance_level++;' . "\n")
                    ->write('$this->inheritance_level = $env->current_inheritance_level;' . "\n")
                    ->write('$env->active_inheritance_level = $env->current_inheritance_level;' . "\n")
                    ->outdent()
                    ->write('} else {' . "\n")
                    ->indent()
                    // 顶层渲染场景重置计数，对应原render方法的初始化逻辑
                    ->write('$this->inheritance_level = 0;' . "\n")
                    ->write('$env->active_inheritance_level = 0;' . "\n")
                    ->write('$env->current_inheritance_level = 0;' . "\n")
                    ->outdent()
                    ->write('}' . "\n");
            }
        });

        // 若需要在display执行完后做出栈、层级递减操作，可向display_end节点注入对应逻辑

        return $node;
    }

    public function leaveNode(Node $node, Environment $env): ?Node
    {
        return $node;
    }

    public function getPriority(): int
    {
        return 0;
    }
}

• 编写Twig扩展，注册自定义节点访问器

<?php
use Twig\Extension\AbstractExtension;

class TemplateTrackExtension extends AbstractExtension
{
    public function getNodeVisitors(): array
    {
        return [new TemplateTrackNodeVisitor()];
    }
}

• 扩展Environment类，实现依赖的属性和方法
  原有逻辑中调用的addTemplateStack()、继承层级相关属性，直接在自定义Environment子类中实现即可，不需要耦合模板基类：

<?php
use Twig\Environment as BaseEnvironment;

class CustomEnvironment extends BaseEnvironment
{
    public int $current_inheritance_level = 0;
    public int $active_inheritance_level = 0;
    protected array $templateStack = [];

    public function addTemplateStack(string $templateName): void
    {
        $this->templateStack[] = $templateName;
    }

    // 按需实现模板栈读取、清空等辅助方法
}

• 初始化Twig时注册扩展即可生效

$loader = new \Twig\Loader\FilesystemLoader('/path/to/templates');
$twig = new CustomEnvironment($loader);
$twig->addExtension(new TemplateTrackExtension());

方案说明 #

• 该方案为官方明确支持的扩展方式，不会随Twig3小版本更新出现兼容问题
• 所有注入的逻辑会在模板编译时写入生成的模板类缓存，运行时无额外性能损耗
• 若需要扩展其他逻辑，只需要在节点访问器中匹配对应节点、注入编译代码即可，覆盖能力比重写基类方法更灵活

内容的提问来源于stack exchange，提问作者ZenithS