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>

あるいは、どうしても以前の振る舞い（true に対する "1" など）が必要なら、値を明示的に文字列にキャストします。

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

この変更によって曖昧さがなくなり、引用符なしの文字列をより自由に使えるようになります。

削除された機能と非推奨の機能

予約された変数: $__（アンダースコア 2 つ）で始まる変数と $this 変数は Latte 内部用に予約されています。既定では使えますが非推奨の警告が出ます。厳格な解析を有効にした場合にのみコンパイルエラーになります。内部変数 $ʟ_… と $GLOBALS は常に禁止です。

undefined-safe 演算子: PHP 8 より前に作られた Latte 固有の機能である ??-> 演算子は削除されました。歴史的な遺物です。標準の PHP の nullsafe 演算子 ?-> を使ってください。

フィルタローダー Engine::addFilterLoader() メソッドは非推奨となり削除されました。Latte のほかの場所には見られない一貫性を欠いた仕組みでした。

日付フォーマット グローバル状態を避けるため、静的プロパティ Latte\Runtime\Filters::$dateFormat は削除されました。

新機能

移行しながら、新しい機能を楽しみ始められます。

  • スマートな HTML 属性: class や style に配列を渡せます。null の属性は自動的に消えます。
  • nullsafe フィルタ: {$var?|filter} で null 値へのフィルタ適用をスキップできます。
  • n:elseif: n:if や n:else と並べて n:elseif が使えるようになりました。
  • 簡潔な構文: <div n:if={$cond}> のように引用符なしで書けます。
  • toggle フィルタ: |toggle で真偽値属性を手動で制御できます。
バージョン: 3.x