TYPO3 v14 : trois changements brutaux Fluid 5 pour les intégrateurs

Après les nouveautés stratégiques, les fonctionnalités pratiques et les changements d'asset handling de TYPO3 v14, il est temps de parler de Fluid 5. TYPO3 v14 apporte la nouvelle version de Fluid - et celle-ci fait le ménage en profondeur.

Trois changements radicaux concernent directement les templates Fluid. La bonne nouvelle : TYPO3 13.4.21 écrit déjà des avertissements de dépréciation dans le journal si tes templates sont concernés. Tu peux donc déjà vérifier dès maintenant.

1) Les sections CDATA ne sont plus supprimées.

Ce qui change

Jusqu'à présent, Fluid supprimait complètement le code dans les blocs < ![CDATA[ ]]>. Cela n'a jamais été documenté, mais beaucoup l'ont utilisé comme solution de contournement pour commenter le code des templates.

Cela ne fonctionne plus à partir de Fluid 5. Les sections CDATA ont maintenant une autre signification : elles résolvent un ancien problème avec le CSS et le JavaScript en ligne dans les templates Fluid.

Le problème que CDATA résout maintenant

La syntaxe des fluides avec des accolades { } entre en conflit avec CSS et JavaScript. Une Media Query comme @media (min-width : 1000px) { ... } ou JavaScript avec des objets comme const data = {key : value} ont jusqu'à présent embrouillé Fluid.

C'est pourquoi Fluid 5 introduit une nouvelle syntaxe en blocs CDATA :

<f:variable name="color" value="red" />
<style>
< ![CDATA[
    @media (min-width : 1000px) {
        p {
            background-color : {{{color}} ;}
        }
    }
]]>
</style>

La règle : à l'intérieur de < ![CDATA[ ]]>, Fluid ignore la syntaxe { } normale. A la place, tu utilises trois accolades {{{ }}} pour les variables et les ViewHelper.

Les ViewHelpers basés sur des balises ne fonctionnent plus du tout dans les blocs CDATA - seulement la syntaxe en ligne avec trois accolades.

Ce que tu dois faire

Si tu as utilisé CDATA pour commenter :

Remplace < ![CDATA[ ]]> par le <f:comment> ViewHelper :

<!-- Alt (ne fonctionne plus) : -->
< ![CDATA[
<f:for each="{items}" as="item">
    {item.title}
</f:for>
]]>
<!-- Nouveau : -->
<f:comment>
<f:for each="{items}" as="item">
    {item.title}
</f:for>
</f:comment>

L'avantage : depuis TYPO3 13, <f:comment> ignore également les syntaxes fluides erronées. Tu peux donc également commenter le balisage invalide.

Si tu as des CSS ou JavaScript en ligne dans les templates :

Cela reste une mauvaise pratique. Mais si tu ne peux pas l'éviter, la nouvelle syntaxe CDATA fonctionne.

Mieux : utilise les attributs data-*, les CSS Custom Properties ou des points de terminaison API dédiés pour transmettre des valeurs dynamiques à CSS et JavaScript.

Projets concernés

Depuis TYPO3 13.4.21, Fluid écrit une déprécation dans le journal lorsqu'il trouve < ![CDATA[ ]]> à commenter. Vérifie ton journal de dépréciation avant de migrer vers la v14.

2. les noms de variables avec un sous-préfixe sont interdits.

Ce qui change

Fluid 5 réserve tous les noms de variables commençant par un underscore à un usage interne. Ceci est comparable à {_all}, qui existe depuis plus longtemps.

Ces exemples ne fonctionnent plus :

<f:variable name="_temp" value="une valeur temporaire" />
{_temp}
<f:for each="{myArray}" as="_item">
    {_item}
</f:for>
<f:render partial="Footer" arguments="{_data : myData}" />

Également en code PHP :

$view->assign('_data', $myData) ;
$view->assignMultiple([
    '_data' => $myData,
]) ;

Tous ces cas soulèvent une exception à partir du fluide 5 :

#1756622558 TYPO3Fluid\\Fluid\Core\\Variables\\InvalidVariableIdentifierException
Les identificateurs de variables ne peuvent pas commencer par un "_" : _myVariable

Ce qui n'est PAS concerné

Les noms de propriétés et les clés de tableaux continuent de fonctionner avec le soulignement :

{myArray._myKey}
{myObject._myProperty}

Les variables internes comme {_all} sont conservées :

<f:render partial="Footer" arguments="{_all}"/>

Migration

Simple : renommez les variables. Au lieu de _temp, utilise temp, au lieu de _item, utilise item.

Depuis TYPO3 13.4.21, Fluid écrit ici aussi une déprécation dans le journal si des noms de variables concernés sont trouvés.

3. typage strict dans les ViewHelpers

Fluid 5 devient plus strict en matière de types. Cela concerne trois domaines :

3.1 Validation plus stricte des arguments ViewHelper.

Jusqu'à présent, Fluid avait de nombreux points aveugles en ce qui concerne la validation des arguments. Les ViewHelpers ne pouvaient pas se fier aux types qu'ils avaient définis dans leur API.

Désormais, Fluid valide de manière plus stricte. Les arguments qui passaient auparavant pour "valides" (mais qui ne correspondaient pas à l'API ViewHelper) sont désormais rejetés.

Bonne nouvelle : Fluid convertit automatiquement les types simples. Un ViewHelper qui attend une chaîne de caractères accepte également un int.

Pour les intégrateurs : certains appels ViewHelper qui fonctionnaient auparavant peuvent maintenant échouer - mais il s'agissait généralement de bugs dans le code du template.

Pour les développeurs d'extensions : tu peux maintenant faire confiance aux types d'arguments et supprimer ta propre logique de validation.

3.2 Valeurs nulles dans les ViewHelpers basés sur des tags

Jusqu'à présent, Fluids TagBuilder traitait les valeurs nulles comme des chaînes vides. Cela conduisait à des attributs HTML avec une valeur vide :

<f:form.textfield name="myTextBox" placeholder="{variableThatMightBeNull}" />

Fluid 4 et antérieurs :

<input type="text" name="myTextBox" placeholder="" />

Fluide 5 :

<input type="text" name="myTextBox" />

L'attribut est complètement supprimé.

ViewHelper concernés dans TYPO3 Core :

• <f:media> et <f:image>.
• <f:asset.css> et <f:asset.script>.
• <f:form> et <f:form.*>
• <f:link.*> (sauf <f:link.typolink>, qui utilise TypoScript)
• <f :[be.link](<http://be.link>)>
• <be:lien.*>
• <be:thumbnail>

Impact pratique : dans la plupart des cas, peu importe. Mais pour certains ViewHelpers (par ex. <f:image>), le Core a dû être adapté pour que l'attribut alt soit toujours rendu - même si la valeur est nulle.

3.3 Déclarations de type "return" dans les classes ViewHelper

La ViewHelperInterface de Fluid exige maintenant des types de retour explicites pour toutes les méthodes.

Si tu développes tes propres ViewHelper, tu dois les adapter :

class MyViewHelper extends AbstractViewHelper
{
    // render() doivent spécifier un type de retour (pas void)
    public function render() : string
    {
        return 'Hello World' ;
    }
    // initializeArguments() a besoin de void
    fonction publique initializeArguments() : void
    {
        $this->registerArgument('name', 'string', 'The name') ;
    }
}

Les propriétés ne sont PAS concernées :

class MyViewHelper extends AbstractViewHelper
{
    protected $escapeOutput = false ; // Pas de déclaration de type nécessaire
    protected $escapeChildren = false ;
}

Cette modification est rétrocompatible. Tu peux donc adapter tes extensions dès maintenant, et elles fonctionneront également avec TYPO3 13 et les versions antérieures.

Vérification automatique difficile

Malheureusement, la plupart de ces modifications ne peuvent pas être analysées automatiquement. Elles dépendent de valeurs de variables concrètes qui sont transmises aux templates au moment de l'exécution.

Le point positif : la plupart des problèmes détectés par Fluid 5 étaient déjà des bugs auparavant - par exemple lorsqu'un tableau a été transmis à un ViewHelper qui attend une chaîne de caractères.

La stratégie sous-jacente

Fluid 5 fait le ménage dans les dettes techniques :

• Une syntaxe documentée plutôt que des solutions de contournement : CDATA reçoit une fonction officielle au lieu d'être utilisé comme hack.
• Espaces de noms plus clairs : préfixe underscore pour les variables internes, afin que les futures versions de Fluid ne génèrent pas de conflits.
• Sécurité des types : les ViewHelper peuvent se fier à leur API, moins de programmation défensive nécessaire.

Cela correspond à l'image de TYPO3 v14 : moins d'héritage, des structures plus claires, des standards modernes.

Comment se préparer

Peut être testé dès maintenant :

Depuis TYPO3 13.4.21, Fluid Deprecations écrit dans le journal si tes templates sont concernés par les deux premiers breaking changes :

• CDATA pour commenter
• Noms de variables avec préfixe underscore

Vérifie ton journal des dépréciations avant de migrer vers la v14.

Extension Scanner pour Custom ViewHelper :

L'Extension Scanner trouve les ViewHelpers sans déclarations de type "return". Si tu développes tes propres extensions, laisse-le fonctionner.

Tests d'exécution :

Les autres modifications (validation des arguments, gestion des nulls) dépendent des valeurs d'exécution. Un scan automatique n'est pas possible. Teste tes templates de manière approfondie après la mise à jour.

Comment rester informé

TYPO3 v14 est encore en cours de développement. Je continue à filtrer les modifications pertinentes du ChangeLog et je les présente ici sur le blog.

Si tu veux recevoir les mises à jour directement, inscris-toi à ma newsletter TYPO3. Tu y recevras les développements les plus importants sous forme compacte - sans bruit, seulement ce qui est vraiment pertinent.

Pour TYPO3 v14, il y aura bien sûr à nouveau un cours vidéo complet - dès que la version sera plus proche de la publication.

Sources & liens

Tous les exemples de code de cet article proviennent directement du TYPO3 ChangeLog officiel et ont été repris tels quels.

Breaking #108148 - Sections CDATA dans les templates fluides plus jamais supprimées

Fonctionnalité #108148 - Syntaxe fluide alternative pour les sections CDATA

Breaking #108148 - Désactiver les noms de variables de fluide avec le préfixe Underscore

Breaking #108148 - Types stricts dans Fluid ViewHelpers