Миграция с Latte 3.0
********************

.[perex]
Latte 3.1 приносит несколько улучшений и изменений, которые делают шаблоны безопаснее и удобнее в написании. Большинство изменений обратно совместимы, но некоторые требуют внимания при миграции. Это руководство обобщает несовместимые изменения и способы с ними справиться.

Latte 3.1 требует **PHP 8.2** или новее.


Умные атрибуты и миграция
=========================

Самое значительное изменение в Latte 3.1 - новое поведение [умных атрибутов |/html-attributes]. Оно затрагивает то, как отрисовываются значения `null` и логические значения в атрибутах `data-`.

1.  **Значения `null`:** раньше `title={$null}` отрисовывалось как `title=""`. Теперь атрибут полностью опускается.
2.  **Атрибуты `data-`:** раньше `data-foo={=true}` / `data-foo={=false}` отрисовывалось как `data-foo="1"` / `data-foo=""`. Теперь отрисовывается как `data-foo="true"` / `data-foo="false"`.

Чтобы вы могли найти места, где вывод в вашем приложении изменился, Latte предоставляет инструмент для миграции.


Предупреждения о миграции
-------------------------

Вы можете включить [предупреждения о миграции |/develop#Предупреждения о миграции], которые во время отрисовки предупредят вас, если вывод отличается от Latte 3.0.

```php
$latte = new Latte\Engine;
$latte->setFeature(Latte\Feature::MigrationWarnings);
```

После включения проверяйте логи приложения или панель Tracy на наличие `E_USER_WARNING`. Каждое предупреждение укажет на конкретную строку и столбец в шаблоне.

**Как устранить предупреждения:**

Если новое поведение верное (например, вы хотите, чтобы пустой атрибут исчез), подтвердите это фильтром `|accept`, который подавит предупреждение:

```latte
<div title={$var|accept}></div>
```

Если вы хотите сохранить атрибут пустым (например, `title=""`) вместо того, чтобы его опустить, используйте оператор объединения с null:

```latte
<div title={$var ?? ''}></div>
```

А если вам строго нужно старое поведение (например, `"1"` для `true`), явно приведите значение к строке:

```latte
<div data-foo={(string) $bool}></div>
```

**После устранения всех предупреждений:**

Когда все предупреждения устранены, выключите предупреждения о миграции и **удалите все** фильтры `|accept` из шаблонов, потому что они больше не нужны.


Строгие типы
============

Latte 3.1 по умолчанию включает `declare(strict_types=1)` для всех скомпилированных шаблонов. Это повышает типобезопасность, но может вызвать ошибки типов в PHP-выражениях внутри шаблонов, если вы полагались на нестрогую типизацию.

Если исправить типы сразу не получается, вы можете отключить это поведение:

```php
$latte->setFeature(Latte\Feature::StrictTypes, false);
```


Глобальные константы
====================

Парсер шаблонов был улучшен, чтобы лучше различать простые строки и константы. В результате перед глобальными константами теперь нужно ставить обратный слеш `\`.

```latte
{* Старый способ (выдаёт предупреждение; в будущем будет истолкован как строка 'PHP_VERSION') *}
{if PHP_VERSION > ...}

{* Новый способ (правильно истолкован как константа) *}
{if \PHP_VERSION > ...}
```

Это изменение устраняет неоднозначность и позволяет свободнее использовать строки без кавычек.


Удалённые и устаревшие возможности
==================================

**Зарезервированные переменные:** переменные, начинающиеся с `$__` (двойное подчёркивание), и переменная `$this` зарезервированы для внутренних нужд Latte. По умолчанию их использование ещё работает, но выдаёт предупреждение об устаревании; только при включённом строгом разборе оно приводит к ошибке компиляции. Внутренние переменные `$ʟ_…` и `$GLOBALS` запрещены всегда.

**Оператор, безопасный к неопределённым значениям:** оператор `??->`, который был особенностью Latte, созданной ещё до PHP 8, удалён. Это исторический пережиток. Используйте стандартный nullsafe-оператор PHP `?->`.

**Загрузчик фильтров**
Метод `Engine::addFilterLoader()` был объявлен устаревшим и удалён. Это была непоследовательная концепция, которая нигде больше в Latte не встречается.

**Формат даты**
Статическое свойство `Latte\Runtime\Filters::$dateFormat` было удалено, чтобы избежать глобального состояния.


Новые возможности
=================

Во время миграции вы можете начать пользоваться новыми возможностями:

- **Умные HTML-атрибуты:** передавайте массивы в `class` и `style`, атрибуты со значением `null` опускаются автоматически.
- **Nullsafe-фильтры:** используйте `{$var?|filter}`, чтобы пропустить фильтрацию значений null.
- **`n:elseif`:** теперь вы можете использовать `n:elseif` рядом с `n:if` и `n:else`.
- **Упрощённый синтаксис:** пишите `<div n:if={$cond}>` без кавычек.
- **Фильтр toggle:** используйте `|toggle` для ручного управления логическими атрибутами.