Migration from Latte 2 to 3
***************************

.[perex]
Latte 3 has a completely rewritten compiler and a formally well-defined grammar. This should match Latte 2 as closely as possible, but there are some constructs that need minor tweaking.

In practice, it turns out that the vast majority of the templates do not need any modification and work the same in Latte 2 as they do in Latte 3. But how to detect incompatibilities?

**First, install the transition version Latte 2.11.**

This version doesn't bring any new features, it just provides a warning using E_USER_DEPRECATED for cases it knows the new Latte won't support, and more importantly advises you how to fix them. To go through all the templates and test if they are compatible, you can use the [Linter|/develop#linter] tool that you run from the console:

```shell
vendor/bin/latte-lint <path>
```

Once you have resolved possible incompatibilities, upgrade to Latte 3.0. **And run Linter again** to make sure the new strict parser really understands all templates.


API Changes
===========

The API changes only apply to adding custom tags. The rest of the API remains the same as version 2, i.e. the same way to render templates, pass parameters, register filters.

The exception is the replacement of the so-called dynamic filter `Engine::addFilter(null, ...)` with [filter loader |/extending-latte#Filter Loader], which differs in that it always returns callable and is registered with the `Engine::addFilterLoader()` method.

The API for adding custom tags is completely different, so add-ons designed for Latte 2 won't work with it. See also [#Updates to add-ons].


Syntax Changes
==============

The changes are as follows:

- filters use a comma as parameter separator, previously `|filter: arg : arg` is now `|filter: arg, arg`
- the `{label foo}...{/label}` tag is always paired, unpaired should be written `{label /}`
- on the other hand, the `{_'text'}` tag is always unpaired, the paired `{_}...{/}` is replaced by the new `{translate}...{/translate}`
- pseudo-strings such as `{block foo-$var}` need to be written in quotes `{block "foo-$var"}` or add compound brackets `{block foo-{$var}}`
- this also applies to attributes, i.e. instead of `n:block="foo-$var"` use `n:block="foo-{$var}"`.
- it is necessary to be case sensitive for filters in Latte 3
- The `{do ...}` or `{php ...}` tag can only contain expressions, to use any PHP register [RawPhpExtension |/develop#RawPhpExtension].

And more edge cases:

- the `n:inner-xxx`, `n:tag-xxx` and `n:ifcontent` attributes cannot be used on void HTML elements
- the `n:inner-snippet` attribute must be written without inner-
- the tags `</script>` and `</style>` must be terminated
- the magic variable `$iterations` has been removed (not to be confused with `$iterator`!)
- replace the `{includeblock file.latte}` tag with [`{include file.latte with blocks}`|/tags#include] or [`{import}`|/template-inheritance#horizontal-reuse]
- `{include "abc"}` should be written as `{include file "abc"}` unless `"abc"` contains a period and it is clear that it is a file


Updates to Add-Ons
==================

With the complete rewrite of the parser, the way to write custom tags has completely changed. If you have custom tags created for Latte, you will need to re-write them for version 3, see [documentation|/creating-extension].

If you are using a foreign add-on that adds tags, you will need to wait until the author releases a version for Latte 3. The `nette/application`, `nette/caching` and `nette/forms` libraries in version 3.1, as well as Texy, have already been updated and work with both Latte 2 and 3.


nette/application
-----------------

.[note]
When using Nette normally, this extension is set automatically and there is no need to change anything.

Old code for Latte 2:

```php
$latte->onCompile[] = function ($latte) {
	Nette\Bridges\ApplicationLatte\UIMacros::install($latte->getCompiler());
};

$latte->addProvider('uiControl', $control);
$latte->addProvider('uiPresenter', $control->getPresenter());
```

New code for Latte 3:

```php
$latte->addExtension(new Nette\Bridges\ApplicationLatte\UIExtension($control));
```

UIExtension adds `n:href`, `{link}`, `{control}`, `{snippet}`, etc. The tags for snippets are thus moved from Latte itself to the `nette/application` library. In Latte 3, the presenter method `templatePrepareFilters()` is no longer called.


nette/forms
-----------

.[note]
When using Nette normally, this extension is set automatically and there is no need to change anything.

Old code for Latte 2:

```php
$latte->onCompile[] = function ($latte) {
	Nette\Bridges\FormsLatte\FormMacros::install($latte->getCompiler());
};
```

New code for Latte 3:

```php
$latte->addExtension(new Nette\Bridges\FormsLatte\FormsExtension);
```


nette/caching
-------------

.[note]
When using Nette normally, this extension is set automatically and there is no need to change anything.

Old code for Latte 2:

```php
$latte->onCompile[] = function ($latte) {
	$latte->getCompiler()->addMacro('cache', new Nette\Bridges\CacheLatte\CacheMacro);
};

$latte->addProvider('cacheStorage', $cacheStorage);
```

New code for Latte 3:

```php
$latte->addExtension(new Nette\Bridges\CacheLatte\CacheExtension($cacheStorage));
```


Tracy
-----

The panel for Tracy is now also activated as an extension.

Old code for Latte 2:

```php
$latte = new Latte\Engine;
Latte\Bridges\Tracy\LattePanel::initialize($latte);
```

New code for Latte 3:

```php
$latte = new Latte\Engine;
$latte->addExtension(new Latte\Bridges\Tracy\TracyExtension);
```


Translations
------------

TranslatorExtension adds the translation tags `{_'text'}`, new pair `{translate}...{/translate}` and the `|translate` filter.

Old code for Latte 2:

```php
$latte->addFilter('translate', [$translator, 'translate']);
```

New code for Latte 3:

```php
$latte->addExtension(new Latte\Essential\TranslatorExtension($translator));
```

In presenters, it is automatically activated by setting the translator to the template using the `$template->setTranslator($translator)` method. Without this, the translation tags will not be available and you need to register the extension manually or with a configuration file.


Configuration File
==================

In Latte 2 it was possible to register new tags using [config file |application:configuration#Latte] in the `latte › macros` section. In version 3, entire extensions are added this way:

```neon
latte:
	extensions:
		- App\Templating\LatteExtension
		- Latte\Essential\TranslatorExtension(@Nette\Localization\Translator)
```


Do You Develop Add-on for Latte?
================================

You can have support for both versions of Latte in your library at the same time. To detect the version, it is best to use the `Latte\Engine::VERSION` constant to separate the use of `onCompile[]` and `addMacro()` from the new `addExtension()`:

```php
if (version_compare(Latte\Engine::VERSION, '3', '<')) {
	// Latte 2 initialization
	$this->latte->onCompile[] = function ($latte) {
		$latte->addMacro(/* ... */);
	};
} else {
	// Latte 3 initialization
	$this->latte->addExtension(/* ... */);
}
```

As an example, let's try rewriting the following code intended for Latte 2 into a form for Latte 3:

```php
// old code for Latte 2
$this->latte->onCompile[] = function (Latte\Engine $latte) {
	$set = new Latte\Macros\MacroSet($latte->getCompiler());
	$set->addMacro('foo', 'echo %escape(MyClass:myFunc(%node.word, %node.array))');
};
```

Latte 3 is extended using [extensions|/creating-extension]. A trivial extension adding the `foo` tag would look like this:

```php
// new code for Latte 3
class FooExtension extends Latte\Extension
{
	public function getTags(): array
	{
		return [
			'foo' => [FooNode::class, 'create'], // we will add the FooNode class in a moment
		];
	}
}

// registration
$this->latte->addExtension(new FooExtension);
```

The new compiler is more robust, it doesn't include the previous shortcuts, so it takes a bit more lines of code to write a macro. For example, we can't directly pass a string of PHP code as in Latte 2, instead we create a function. Recall that in Latte 2 the function would look something like this:

```php
// Latte 2
$set->addMacro('foo', function (Latte\MacroNode $node, Latte\PhpWriter $writer) {
	return $writer->write('echo %escape(MyClass:myFunc(%node.word, %node.array))');
});
```

Nevertheless, Latte 3 goes about it in much the same way, only `MacroNode` is called `Latte\Compiler\Tag` and `PhpWriter` is `Latte\Compiler\PrintContext`. But most importantly, there is an extra intermediate step, which is that the function does not return PHP code directly, but returns a node, i.e. a child of `StatementNode`, which is then part of the AST tree. And this node has a method `print(Latte\Compiler\PrintContext $content): string` that returns PHP code:

```php
// Latte 3
class FooNode extends Latte\Compiler\Nodes\StatementNode
{
	public static function create(Latte\Compiler\Tag $tag): self
	{
		$node = new self;
		return $node;
	}

	public function print(Latte\Compiler\PrintContext $context): string
	{
		return $context->format('echo ...'); // returns PHP code
	}
}
```

Furthermore, the mask in `$context->format()` no longer has `%node.***` abbreviations, it is assumed that you [parse the tag content |/creating-extension#Tag Parsing Function] first. So we use the parser to parse the content into variables (subnodes), and then we write it out:

```php
use Latte\Compiler\Nodes\Php\Expression\ArrayNode;
use Latte\Compiler\Nodes\Php\ExpressionNode;

class FooNode extends Latte\Compiler\Nodes\StatementNode
{
	public ExpressionNode $subject;
	public ArrayNode $args;

	public static function create(Latte\Compiler\Tag $tag): self
	{
		$node = new self;
		// parsing the content of the tag
		$node->subject = $tag->parser->parseUnquotedStringOrExpression();
		$tag->parser->stream->tryConsume(',');
		$node->args = $tag->parser->parseArguments();
		return $node;
	}

	public function print(Latte\Compiler\PrintContext $context): string
	{
		return $context->format(
			'echo %escape(MyClass:myFunc(%node, %node));',
			$this->subject,
			$this->args,
		);
	}
}
```

Finally, we will add the `getIterator()` method to allow subnodes to be traversed when [traversing |/creating-extension#Node Traverser]:

```php
class FooNode extends Latte\Compiler\Nodes\StatementNode
{
	...

	public function &getIterator(): \Generator
	{
		yield $this->subject;
		yield $this->args;
	}
}
```

{{priority: -1}}
{{leftbar: /@left-menu}}