vendor/twig/twig/src/Template.php line 454

Open in your IDE?
  1. <?php
  3. /*
  4.  * This file is part of Twig.
  5.  *
  6.  * (c) Fabien Potencier
  7.  * (c) Armin Ronacher
  8.  *
  9.  * For the full copyright and license information, please view the LICENSE
  10.  * file that was distributed with this source code.
  11.  */
  13. namespace Twig;
  15. use Twig\Error\Error;
  16. use Twig\Error\RuntimeError;
  18. /**
  19.  * Default base class for compiled templates.
  20.  *
  21.  * This class is an implementation detail of how template compilation currently
  22.  * works, which might change. It should never be used directly. Use $twig->load()
  23.  * instead, which returns an instance of \Twig\TemplateWrapper.
  24.  *
  25.  * @author Fabien Potencier <fabien@symfony.com>
  26.  *
  27.  * @internal
  28.  */
  29. abstract class Template
  30. {
  31.     public const ANY_CALL = 'any';
  32.     public const ARRAY_CALL = 'array';
  33.     public const METHOD_CALL = 'method';
  35.     protected $parent;
  36.     protected $parents = [];
  37.     protected $blocks = [];
  38.     protected $traits = [];
  39.     protected $traitAliases = [];
  40.     protected $extensions = [];
  41.     protected $sandbox;
  43.     private $useYield;
  44.     private ?MacroNamespace $macroNamespace = null;
  46.     public function __construct(
  47.         protected Environment $env,
  48.     ) {
  49.         $this->useYield = $env->useYield();
  50.         $this->extensions = $env->getExtensions();
  51.     }
  53.     /**
  54.      * Returns the template name.
  55.      */
  56.     abstract public function getTemplateName(): string;
  58.     /**
  59.      * Returns debug information about the template.
  60.      *
  61.      * @return array<int, int> Debug information
  62.      */
  63.     abstract public function getDebugInfo(): array;
  65.     /**
  66.      * Returns information about the original template source code.
  67.      */
  68.     abstract public function getSourceContext(): Source;
  70.     /**
  71.      * Returns the escaping strategy the template body was compiled with.
  72.      *
  73.      * This describes the template's own source, not its output: `autoescape`,
  74.      * `escape`, and anything rendered by a parent, embedded, or included
  75.      * template can use another strategy.
  76.      *
  77.      * @return string|false The strategy name or false when the template is not autoescaped
  78.      */
  79.     public function getDefaultEscapeStrategy(): string|false
  80.     {
  81.         return false;
  82.     }
  84.     /**
  85.      * Returns the parent template.
  86.      *
  87.      * This method is for internal use only and should never be called
  88.      * directly.
  89.      *
  90.      * @return self|false The parent template or false if there is no parent
  91.      */
  92.     public function getParent(array $context): self|false
  93.     {
  94.         if (null !== $this->parent) {
  95.             return $this->parent;
  96.         }
  98.         // The compiled doGetParent() may evaluate user expressions (filters,
  99.         // functions, method calls) when the parent name is dynamic. Make sure
  100.         // the sandbox security check runs first so those expressions cannot
  101.         // bypass the allow-list when getParent() is reached before the first
  102.         // ensureSecurityChecked() call on this template (e.g. via a macro call
  103.         // resolved against a parent, or yieldBlock() into a pre-warmed instance).
  104.         $this->ensureSecurityChecked();
  106.         try {
  107.             $parent = $this->doGetParent($context);
  108.         } catch (\Throwable $e) {
  109.             $this->handleException($e);
  110.         }
  112.         if (!$parent) {
  113.             return false;
  114.         }
  116.         if ($parent instanceof TemplateWrapper) {
  117.             $parent = $this->load($parent, -1);
  118.         }
  119.         if ($parent instanceof self) {
  120.             return $this->parents[$parent->getSourceContext()->getName()] = $parent;
  121.         }
  123.         if (!isset($this->parents[$parent])) {
  124.             $this->parents[$parent] = $this->load($parent, -1);
  125.         }
  127.         return $this->parents[$parent];
  128.     }
  130.     protected function doGetParent(array $context): bool|string|self|TemplateWrapper
  131.     {
  132.         return false;
  133.     }
  135.     public function isTraitable(): bool
  136.     {
  137.         return true;
  138.     }
  140.     /**
  141.      * Displays a parent block.
  142.      *
  143.      * This method is for internal use only and should never be called
  144.      * directly.
  145.      *
  146.      * @param string $name    The block name to display from the parent
  147.      * @param array  $context The context
  148.      * @param array  $blocks  The current set of blocks
  149.      */
  150.     public function displayParentBlock($name, array $context, array $blocks = []): void
  151.     {
  152.         foreach ($this->yieldParentBlock($name, $context, $blocks) as $data) {
  153.             echo $data;
  154.         }
  155.     }
  157.     /**
  158.      * Displays a block.
  159.      *
  160.      * This method is for internal use only and should never be called
  161.      * directly.
  162.      *
  163.      * @param string $name      The block name to display
  164.      * @param array  $context   The context
  165.      * @param array  $blocks    The current set of blocks
  166.      * @param bool   $useBlocks Whether to use the current set of blocks
  167.      */
  168.     public function displayBlock($name, array $context, array $blocks = [], $useBlocks = true, ?self $templateContext = null): void
  169.     {
  170.         foreach ($this->yieldBlock($name, $context, $blocks, $useBlocks, $templateContext) as $data) {
  171.             echo $data;
  172.         }
  173.     }
  175.     /**
  176.      * Renders a parent block.
  177.      *
  178.      * This method is for internal use only and should never be called
  179.      * directly.
  180.      *
  181.      * @param string $name    The block name to render from the parent
  182.      * @param array  $context The context
  183.      * @param array  $blocks  The current set of blocks
  184.      *
  185.      * @return string The rendered block
  186.      */
  187.     public function renderParentBlock($name, array $context, array $blocks = []): string
  188.     {
  189.         if (!$this->useYield) {
  190.             $level = ob_get_level();
  191.             if ($this->env->isDebug()) {
  192.                 ob_start();
  193.             } else {
  194.                 ob_start(static function () { return ''; });
  195.             }
  196.             try {
  197.                 $this->displayParentBlock($name, $context, $blocks);
  198.             } catch (\Throwable $e) {
  199.                 while (ob_get_level() > $level) {
  200.                     ob_end_clean();
  201.                 }
  203.                 throw $e;
  204.             }
  206.             return ob_get_clean();
  207.         }
  209.         $content = '';
  210.         foreach ($this->yieldParentBlock($name, $context, $blocks) as $data) {
  211.             $content .= $data;
  212.         }
  214.         return $content;
  215.     }
  217.     /**
  218.      * Renders a block.
  219.      *
  220.      * This method is for internal use only and should never be called
  221.      * directly.
  222.      *
  223.      * @param string $name      The block name to render
  224.      * @param array  $context   The context
  225.      * @param array  $blocks    The current set of blocks
  226.      * @param bool   $useBlocks Whether to use the current set of blocks
  227.      *
  228.      * @return string The rendered block
  229.      */
  230.     public function renderBlock($name, array $context, array $blocks = [], $useBlocks = true): string
  231.     {
  232.         if (!$this->useYield) {
  233.             $level = ob_get_level();
  234.             if ($this->env->isDebug()) {
  235.                 ob_start();
  236.             } else {
  237.                 ob_start(static function () { return ''; });
  238.             }
  239.             try {
  240.                 $this->displayBlock($name, $context, $blocks, $useBlocks);
  241.             } catch (\Throwable $e) {
  242.                 while (ob_get_level() > $level) {
  243.                     ob_end_clean();
  244.                 }
  246.                 throw $e;
  247.             }
  249.             return ob_get_clean();
  250.         }
  252.         $content = '';
  253.         foreach ($this->yieldBlock($name, $context, $blocks, $useBlocks) as $data) {
  254.             $content .= $data;
  255.         }
  257.         return $content;
  258.     }
  260.     /**
  261.      * Returns whether a block exists or not in the current context of the template.
  262.      *
  263.      * This method checks blocks defined in the current template
  264.      * or defined in "used" traits or defined in parent templates.
  265.      *
  266.      * @param string $name    The block name
  267.      * @param array  $context The context
  268.      * @param array  $blocks  The current set of blocks
  269.      *
  270.      * @return bool true if the block exists, false otherwise
  271.      */
  272.     public function hasBlock($name, array $context, array $blocks = []): bool
  273.     {
  274.         if (isset($blocks[$name])) {
  275.             return $blocks[$name][0] instanceof self;
  276.         }
  278.         if (isset($this->blocks[$name])) {
  279.             return true;
  280.         }
  282.         if ($parent = $this->getParent($context)) {
  283.             return $parent->hasBlock($name, $context);
  284.         }
  286.         return false;
  287.     }
  289.     /**
  290.      * Returns all block names in the current context of the template.
  291.      *
  292.      * This method checks blocks defined in the current template
  293.      * or defined in "used" traits or defined in parent templates.
  294.      *
  295.      * @param array $context The context
  296.      * @param array $blocks  The current set of blocks
  297.      *
  298.      * @return array<string> An array of block names
  299.      */
  300.     public function getBlockNames(array $context, array $blocks = []): array
  301.     {
  302.         $names = array_merge(array_keys($blocks), array_keys($this->blocks));
  304.         if ($parent = $this->getParent($context)) {
  305.             $names = array_merge($names, $parent->getBlockNames($context));
  306.         }
  308.         return array_unique($names);
  309.     }
  311.     /**
  312.      * @param string|TemplateWrapper|array<string|TemplateWrapper> $template
  313.      */
  314.     protected function load(string|TemplateWrapper|array $template, int $line, ?int $index = null): self
  315.     {
  316.         try {
  317.             if (\is_array($template)) {
  318.                 return $this->env->resolveTemplate($template)->unwrap($this->env);
  319.             }
  321.             if ($template instanceof TemplateWrapper) {
  322.                 return $template->unwrap($this->env);
  323.             }
  325.             if ($template === $this->getTemplateName()) {
  326.                 $class = static::class;
  327.                 if (false !== $pos = strrpos($class, '___', -1)) {
  328.                     $class = substr($class, 0, $pos);
  329.                 }
  330.             } else {
  331.                 $class = $this->env->getTemplateClass($template);
  332.             }
  334.             return $this->env->loadTemplate($class, $template, $index);
  335.         } catch (Error $e) {
  336.             if (!$e->getSourceContext()) {
  337.                 $e->setSourceContext($this->getSourceContext());
  338.             }
  340.             if ($e->getTemplateLine() > 0) {
  341.                 throw $e;
  342.             }
  344.             if (-1 === $line) {
  345.                 $e->guess();
  346.             } else {
  347.                 $e->setTemplateLine($line);
  348.             }
  350.             throw $e;
  351.         }
  352.     }
  354.     /**
  355.      * @param string|TemplateWrapper|array<string|TemplateWrapper> $template
  356.      *
  357.      * @deprecated since Twig 3.21 and will be removed in 4.0. Use Template::load() instead.
  358.      */
  359.     protected function loadTemplate($template, $templateName = null, ?int $line = null, ?int $index = null): self|TemplateWrapper
  360.     {
  361.         trigger_deprecation('twig/twig', '3.21', 'The "%s" method is deprecated.', __METHOD__);
  363.         if (null === $line) {
  364.             $line = -1;
  365.         }
  367.         if ($template instanceof self) {
  368.             return $template;
  369.         }
  371.         return $this->load($template, $line, $index);
  372.     }
  374.     /**
  375.      * @internal
  376.      *
  377.      * @return $this
  378.      */
  379.     public function unwrap(): self
  380.     {
  381.         return $this;
  382.     }
  384.     /**
  385.      * @internal
  386.      */
  387.     public function isOwnedBy(Environment $env): bool
  388.     {
  389.         return $this->env === $env;
  390.     }
  392.     /**
  393.      * Returns whether getParent() has stopped depending on the context, which
  394.      * only ever happens for a template with no parent or with a constant one.
  395.      */
  396.     public function hasFixedParent(): bool
  397.     {
  398.         return null !== $this->parent;
  399.     }
  401.     /**
  402.      * Returns all blocks.
  403.      *
  404.      * This method is for internal use only and should never be called
  405.      * directly.
  406.      *
  407.      * @return array An array of blocks
  408.      */
  409.     public function getBlocks(): array
  410.     {
  411.         return $this->blocks;
  412.     }
  414.     public function display(array $context, array $blocks = []): void
  415.     {
  416.         foreach ($this->yield($context, $blocks) as $data) {
  417.             echo $data;
  418.         }
  419.     }
  421.     public function render(array $context): string
  422.     {
  423.         if (!$this->useYield) {
  424.             $level = ob_get_level();
  425.             if ($this->env->isDebug()) {
  426.                 ob_start();
  427.             } else {
  428.                 ob_start(static function () { return ''; });
  429.             }
  430.             try {
  431.                 $this->display($context);
  432.             } catch (\Throwable $e) {
  433.                 while (ob_get_level() > $level) {
  434.                     ob_end_clean();
  435.                 }
  437.                 throw $e;
  438.             }
  440.             return ob_get_clean();
  441.         }
  443.         $content = '';
  444.         foreach ($this->yield($context) as $data) {
  445.             $content .= $data;
  446.         }
  448.         return $content;
  449.     }
  451.     /**
  452.      * @return iterable<scalar|\Stringable|null>
  453.      */
  454.     public function yield(array $context, array $blocks = []): iterable
  455.     {
  456.         $context += $this->env->getGlobals();
  457.         $blocks = array_merge($this->blocks, $blocks);
  459.         try {
  460.             $this->ensureSecurityChecked();
  461.             yield from $this->doDisplay($context, $blocks);
  462.         } catch (\Throwable $e) {
  463.             $this->handleException($e);
  464.         }
  465.     }
  467.     /**
  468.      * @return iterable<scalar|\Stringable|null>
  469.      */
  470.     public function yieldBlock($name, array $context, array $blocks = [], $useBlocks = true, ?self $templateContext = null): iterable
  471.     {
  472.         if ($useBlocks && isset($blocks[$name])) {
  473.             $template = $blocks[$name][0];
  474.             $block = $blocks[$name][1];
  475.         } elseif (isset($this->blocks[$name])) {
  476.             $template = $this->blocks[$name][0];
  477.             $block = $this->blocks[$name][1];
  478.             // expose this template's own blocks so nested block() calls resolve against them when the block is rendered directly (e.g. block(name, template))
  479.             $blocks = array_merge($this->blocks, $blocks);
  480.         } else {
  481.             $template = null;
  482.             $block = null;
  483.         }
  485.         // avoid RCEs when sandbox is enabled
  486.         if (null !== $template && !$template instanceof self) {
  487.             throw new \LogicException('A block must be a method on a \Twig\Template instance.');
  488.         }
  490.         if (null !== $template) {
  491.             try {
  492.                 $template->ensureSecurityChecked();
  493.                 yield from $template->$block($context, $blocks);
  494.             } catch (\Throwable $e) {
  495.                 $template->handleException($e);
  496.             }
  497.         } elseif ($parent = $this->getParent($context)) {
  498.             yield from $parent->unwrap()->yieldBlock($name, $context, array_merge($this->blocks, $blocks), false, $templateContext ?? $this);
  499.         } elseif (isset($blocks[$name])) {
  500.             throw new RuntimeError(\sprintf('Block "%s" should not call parent() in "%s" as the block does not exist in the parent template "%s".', $name, $blocks[$name][0]->getTemplateName(), $this->getTemplateName()), -1, $blocks[$name][0]->getSourceContext());
  501.         } else {
  502.             throw new RuntimeError(\sprintf('Block "%s" on template "%s" does not exist.', $name, $this->getTemplateName()), -1, ($templateContext ?? $this)->getSourceContext());
  503.         }
  504.     }
  506.     /**
  507.      * Yields a parent block.
  508.      *
  509.      * This method is for internal use only and should never be called
  510.      * directly.
  511.      *
  512.      * @param string $name    The block name to display from the parent
  513.      * @param array  $context The context
  514.      * @param array  $blocks  The current set of blocks
  515.      *
  516.      * @return iterable<scalar|\Stringable|null>
  517.      */
  518.     public function yieldParentBlock($name, array $context, array $blocks = []): iterable
  519.     {
  520.         if (isset($this->traits[$name])) {
  521.             yield from $this->traits[$name][0]->yieldBlock($this->traitAliases[$name] ?? $name, $context, $blocks, false);
  522.         } elseif ($parent = $this->getParent($context)) {
  523.             yield from $parent->unwrap()->yieldBlock($name, $context, $blocks, false);
  524.         } else {
  525.             throw new RuntimeError(\sprintf('The template has no parent and no traits defining the "%s" block.', $name), -1, $this->getSourceContext());
  526.         }
  527.     }
  529.     /**
  530.      * @internal
  531.      */
  532.     public function getMacroNamespace(): MacroNamespace
  533.     {
  534.         return $this->macroNamespace ??= new MacroNamespace($this, $this->loadDeclaredMacros());
  535.     }
  537.     /**
  538.      * @return array<string, TwigMacro>
  539.      */
  540.     protected function loadDeclaredMacros(): array
  541.     {
  542.         return [];
  543.     }
  545.     /**
  546.      * Runs the sandbox security check against the current sandbox state.
  547.      *
  548.      * @internal
  549.      */
  550.     public function ensureSecurityChecked(): void
  551.     {
  552.     }
  554.     /**
  555.      * Checks the "use" tag against the sandbox policy.
  556.      *
  557.      * The constructor resolves "use" traits eagerly, which reaches the loader,
  558.      * so that tag alone is checked here; the rest of the policy still runs at
  559.      * render time.
  560.      *
  561.      * @internal
  562.      */
  563.     public function ensureTraitsAllowed(): void
  564.     {
  565.         try {
  566.             $this->checkTraitsAllowed();
  567.         } catch (\Throwable $e) {
  568.             $this->handleException($e);
  569.         }
  570.     }
  572.     /**
  573.      * @internal
  574.      */
  575.     protected function checkTraitsAllowed(): void
  576.     {
  577.     }
  579.     /**
  580.      * @internal
  581.      */
  582.     protected function throwUninitializedMacroNamespace(int $line): never
  583.     {
  584.         throw new RuntimeError(\sprintf('Macros imported in the body of template "%s" are not available because the body was not rendered; move the "import" or "from" tag inside the block or the macro that uses it.', $this->getTemplateName()), $line, $this->getSourceContext());
  585.     }
  587.     /**
  588.      * Auto-generated method to display the template with the given context.
  589.      *
  590.      * @param array $context An array of parameters to pass to the template
  591.      * @param array $blocks  An array of blocks to pass to the template
  592.      *
  593.      * @return iterable<scalar|\Stringable|null>
  594.      */
  595.     abstract protected function doDisplay(array $context, array $blocks = []): iterable;
  597.     private function handleException(\Throwable $error): never
  598.     {
  599.         if ($error instanceof Error) {
  600.             if (!$error->getSourceContext()) {
  601.                 $error->setSourceContext($this->getSourceContext());
  602.             }
  603.             if (-1 === $error->getTemplateLine()) {
  604.                 $error->guess();
  605.             }
  607.             throw $error;
  608.         }
  610.         $error = new RuntimeError(\sprintf('An exception has been thrown during the rendering of a template ("%s").', $error->getMessage()), -1, $this->getSourceContext(), $error);
  611.         $error->guess();
  613.         throw $error;
  614.     }
  615. }