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

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. }