Миграция с Latte 3.0

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

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

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

Самое значительное изменение в Latte 3.1 – новое поведение умных атрибутов. Оно затрагивает то, как отрисовываются значения 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 предоставляет инструмент для миграции.

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

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

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

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

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

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

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

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

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

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

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

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

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

Строгие типы

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

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

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

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

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

{* Старый способ (выдаёт предупреждение; в будущем будет истолкован как строка '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 для ручного управления логическими атрибутами.