{layout file, vars} passes explicit variables to the parent template

Arguments after the template name are passed to the layout only and are
not created in the current template, so child blocks do not see them.
An explicit argument overrides a same-named parameter of the child.
Works with {extends} and {layout auto} too; {layout none} forbids them.
The comma before arguments is required.

Author: dg

docs/reference/tags.md

@@ -27,7 +27,7 @@ out of sync with the code.
 | `{dump}` | `DumpNode::create` |  |
 | `{embed}` | `EmbedNode::create` | loose content becomes an implicit `{block default}` |
 | `{exitIf}` | `JumpNode::create` |  |
-| `{extends}` | `ExtendsNode::create` |  |
+| `{extends}` | `ExtendsNode::create` | optional explicit variables for the parent template: `{extends file, var: value}` |
 | `{first}` | `FirstLastSepNode::create` |  |
 | `{for}` | `ForNode::create` |  |
 | `{foreach}` | `ForeachNode::create` |  |

src/Latte/Essential/Nodes/ExtendsNode.php

@@ -8,6 +8,7 @@
 namespace Latte\Essential\Nodes;
 
 use Latte\CompileException;
+use Latte\Compiler\Nodes\Php\Expression\ArrayNode;
 use Latte\Compiler\Nodes\Php\ExpressionNode;
 use Latte\Compiler\Nodes\Php\Scalar\BooleanNode;
 use Latte\Compiler\Nodes\Php\Scalar\NullNode;
@@ -17,12 +18,13 @@
 
 
 /**
- * {extends 'parent.latte'}
- * {layout 'layout.latte'}
+ * {extends 'parent.latte' [, args]}
+ * {layout 'layout.latte' [, args]}
  */
 class ExtendsNode extends StatementNode
 {
 	public ExpressionNode $extends;
+	public ArrayNode $args;
 
 
 	public static function create(Tag $tag): static
@@ -38,18 +40,25 @@ public static function create(Tag $tag): static
 		} else {
 			$node->extends = $tag->parser->parseUnquotedStringOrExpression();
 		}
+		$tag->parser->consumeCommaBeforeArguments();
+		$node->args = $tag->parser->parseArguments();
+		if ($node->args->items && $node->extends instanceof BooleanNode) {
+			throw new CompileException("{{$tag->name} none} cannot have arguments.", $tag->position);
+		}
 		return $node;
 	}
 
 
 	public function print(PrintContext $context): string
 	{
-		return $context->format('$this->parentName = %node;', $this->extends);
+		return $context->format('$this->parentName = %node;', $this->extends)
+			. ($this->args->items ? $context->format('$this->parentArgs = %node;', $this->args) : '');
 	}
 
 
 	public function &getIterator(): \Generator
 	{
 		yield $this->extends;
+		yield $this->args;
 	}
 }

src/Latte/Runtime/Template.php

@@ -36,6 +36,9 @@ class Template
 	/** @internal */
 	protected string|false|null $parentName = null;
 
+	/** @var mixed[]  variables passed explicitly to the parent template @internal */
+	protected array $parentArgs = [];
+
 	/** @var mixed[][] */
 	protected array $varStack = [];
 
@@ -96,7 +99,7 @@ public function render(?string $block = null): void
 				trigger_error("Content outside of blocks is ignored when the template extends another one (in '$this->name').", E_USER_WARNING);
 			}
 			$this->params = $params;
-			$this->createTemplate($parentName, $params, 'extends')->render($block);
+			$this->createTemplate($parentName, $this->parentArgs + $params, 'extends')->render($block);
 
 		} elseif ($block !== null) { // single block rendering
 			$this->renderBlock($block, $this->params);

tests/tags/extends.args.phpt

@@ -0,0 +1,72 @@
+<?php declare(strict_types=1);
+
+/**
+ * Test: {layout file, args} & {extends file, args} explicit variables for parent template
+ */
+
+use Tester\Assert;
+
+require __DIR__ . '/../bootstrap.php';
+
+
+test('arguments are passed to the layout', function () {
+	$latte = new Latte\Engine;
+	$latte->setLoader(new Latte\Loaders\StringLoader([
+		'layout' => 'foo={$foo} {include content}',
+		'main' => '{layout "layout", foo: 123}{block content}child{/block}',
+	]));
+	Assert::same('foo=123 child', $latte->renderToString('main'));
+});
+
+
+test('argument beats template parameter of the same name, blocks keep the original', function () {
+	$latte = new Latte\Engine;
+	$latte->setLoader(new Latte\Loaders\StringLoader([
+		'layout' => 'foo={$foo} {include content}',
+		'main' => '{extends "layout", foo: "explicit"}{block content}{$foo}{/block}',
+	]));
+	Assert::same('foo=explicit param', $latte->renderToString('main', ['foo' => 'param']));
+});
+
+
+test('arguments are not created in the child template', function () {
+	$latte = new Latte\Engine;
+	$latte->setLoader(new Latte\Loaders\StringLoader([
+		'layout' => '{include content}',
+		'main' => '{layout "layout", foo: 123}{block content}{$foo ?? "undefined"}{/block}',
+	]));
+	Assert::same('undefined', $latte->renderToString('main'));
+});
+
+
+test('{layout auto} with arguments', function () {
+	$latte = new Latte\Engine;
+	$latte->setLoader(new Latte\Loaders\StringLoader([
+		'layout' => 'foo={$foo} {include content}',
+		'main' => '{layout auto, foo: 123}{block content}child{/block}',
+	]));
+	$latte->addProvider('coreParentFinder', fn() => 'layout');
+	Assert::same('foo=123 child', $latte->renderToString('main'));
+});
+
+
+test('{layout none} with arguments is forbidden', function () {
+	$latte = new Latte\Engine;
+	$latte->setLoader(new Latte\Loaders\StringLoader);
+	Assert::exception(
+		fn() => $latte->compile('{layout none, foo: 123}'),
+		Latte\CompileException::class,
+		'{layout none} cannot have arguments%a%',
+	);
+});
+
+
+test('comma before arguments is required', function () {
+	$latte = new Latte\Engine;
+	$latte->setLoader(new Latte\Loaders\StringLoader);
+	Assert::exception(
+		fn() => $latte->compile('{layout "layout" foo: 123}'),
+		Latte\CompileException::class,
+		'Unexpected %a%',
+	);
+});