Migration depuis Latte 3.0

Latte 3.1 apporte plusieurs améliorations et changements qui rendent les templates plus sûrs et plus agréables à écrire. La plupart des changements sont rétrocompatibles, mais certains demandent de l'attention lors de la migration. Ce guide récapitule les ruptures de compatibilité et la façon de les traiter.

Latte 3.1 exige PHP 8.2 ou une version plus récente.

Attributs intelligents et migration

Le changement le plus important de Latte 3.1 est le nouveau comportement des attributs intelligents. Il touche la façon dont les valeurs null et les valeurs booléennes des attributs data- sont rendues.

  1. Valeurs null : auparavant, title={$null} produisait title="". Désormais, l'attribut disparaît complètement.
  2. Attributs data- : auparavant, data-foo={=true} / data-foo={=false} produisaient data-foo="1" / data-foo="". Désormais, cela donne data-foo="true" / data-foo="false".

Pour vous aider à repérer les endroits où la sortie a changé dans votre application, Latte fournit un outil de migration.

Avertissements de migration

Vous pouvez activer les avertissements de migration, qui vous préviendront pendant le rendu si la sortie diffère de celle de Latte 3.0.

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

Une fois activés, surveillez les logs de votre application ou la barre Tracy à la recherche de E_USER_WARNING. Chaque avertissement pointe vers la ligne et la colonne précises dans le template.

Comment traiter les avertissements :

Si le nouveau comportement est le bon (par exemple, vous voulez que l'attribut vide disparaisse), confirmez-le avec le filtre |accept pour supprimer l'avertissement :

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

Si vous voulez conserver l'attribut vide (par exemple title="") au lieu de le supprimer, utilisez l'opérateur de coalescence nulle :

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

Ou, si vous tenez absolument à l'ancien comportement (par exemple "1" pour true), convertissez explicitement la valeur en chaîne :

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

Une fois tous les avertissements traités :

Quand plus aucun avertissement ne subsiste, désactivez les avertissements de migration et supprimez tous les filtres |accept de vos templates : ils ne servent plus à rien.

Types stricts

Latte 3.1 active par défaut declare(strict_types=1) pour tous les templates compilés. Cela renforce la sûreté du typage, mais peut provoquer des erreurs de type dans les expressions PHP de vos templates si vous vous appuyiez sur le typage souple.

Si vous ne pouvez pas corriger les types tout de suite, vous pouvez désactiver ce comportement :

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

Constantes globales

Le parser de templates distingue désormais mieux les chaînes simples des constantes. En conséquence, les constantes globales doivent maintenant être préfixées d'une barre oblique inverse \.

{* Ancienne écriture (lève un avertissement ; à l'avenir, sera interprétée comme la chaîne 'PHP_VERSION') *}
{if PHP_VERSION > ...}

{* Nouvelle écriture (correctement interprétée comme une constante) *}
{if \PHP_VERSION > ...}

Ce changement lève l'ambiguïté et vous laisse utiliser plus librement les chaînes sans guillemets.

Fonctionnalités supprimées et obsolètes

Variables réservées : les variables commençant par $__ (double tiret bas) et la variable $this sont réservées à l'usage interne de Latte. Par défaut, leur utilisation fonctionne encore, mais déclenche un avertissement d'obsolescence ; ce n'est qu'avec l'analyse stricte activée qu'elle provoque une erreur de compilation. Les variables internes $ʟ_… et $GLOBALS sont toujours interdites.

Opérateur undefined-safe : l'opérateur ??->, spécifique à Latte et créé avant PHP 8, a été supprimé. C'est un vestige historique. Utilisez l'opérateur nullsafe standard de PHP ?->.

Chargeur de filtres La méthode Engine::addFilterLoader() a été dépréciée puis supprimée. C'était un concept incohérent qu'on ne retrouvait nulle part ailleurs dans Latte.

Format de date La propriété statique Latte\Runtime\Filters::$dateFormat a été supprimée pour éviter un état global.

Nouveautés

Pendant la migration, vous pouvez commencer à profiter des nouveautés :

  • Attributs HTML intelligents : passez des tableaux à class et style, les attributs null disparaissent automatiquement.
  • Filtres nullsafe : utilisez {$var?|filter} pour ne pas filtrer les valeurs nulles.
  • n:elseif : vous pouvez désormais utiliser n:elseif aux côtés de n:if et n:else.
  • Syntaxe simplifiée : écrivez <div n:if={$cond}> sans guillemets.
  • Filtre toggle : utilisez |toggle pour contrôler manuellement les attributs booléens.
version: 3.x