Pendant des mois, le convertisseur a eu un bug que je ne voyais pas : chaque ombre de boîte (box shadow) qu’il produisait passait à la trappe. Pas mal rendue — purement et simplement supprimée. La conversion réussissait, l’importation réussissait, les éléments arrivaient, et les ombres n’étaient tout simplement pas là.
Aucune exception. Aucun avertissement dans la console. Aucune requête échouée. Rien dans les journaux. Si vous n’aviez pas construit la page vous-même, vous ne sauriez pas qu’il manquait quelque chose ; vous penseriez simplement que la conversion était médiocre.
Cela vaut la peine d’être mis par écrit, car ce type de problème dépasse largement Elementor, qui n’en est qu’un cas particulier. Le cas général est : vous écrivez dans un système qui ignore les clés qu’il ne reconnaît pas, et une faute de frappe ou une hypothèse périmée se transforme en perte de données permanente et silencieuse.
Pourquoi c’est invisible
Elementor stocke chaque élément sous forme de JSON — un type d’élément plus un objet settings. Au moment du rendu, il parcourt ses contrôles enregistrés et interroge l’objet settings pour chacun d’eux. Une clé qui ne correspond pas à un contrôle enregistré n’est jamais consultée. Elle n’est pas rejetée. Elle n’est simplement jamais lue.
C’est une conception raisonnable : les anciennes données survivent aux mises à jour du plugin, et les clés inconnues d’une version plus récente ne cassent pas une version plus ancienne. C’est aussi pourquoi un mauvais nom de clé ne produit absolument aucun retour. Avec une API qui valide, une mauvaise clé est une erreur au moment de l’écriture, détectée dès l’exécution suivante des tests. Avec une API qui ignore, c’est le silence, découvert par un utilisateur des mois plus tard, si jamais il l’est.
Pourquoi vous ne pouvez pas simplement chercher les noms
La réponse évidente est de vérifier les noms des contrôles dans la documentation. Le problème est que beaucoup d’entre eux ne sont écrits nulle part — ils sont générés.
Elementor possède des contrôles de groupe : des ensembles réutilisables comme la typographie, la bordure, l’arrière-plan, l’ombre de boîte. Vous en attachez un à un widget avec un nom, et les identifiants de contrôle individuels sont composés à l’exécution — le nom du groupe, un tiret bas, puis le nom de chaque champ. Ainsi, un groupe de typographie enregistré sous title produit le contrôle title_font_size. Il n’existe aucun fichier dans lequel cette chaîne apparaît. Vous ne pouvez pas la trouver avec grep. Vous devez connaître la règle et l’appliquer.
C’est exactement la situation où la mémoire, les réponses de forum et les vieux articles de blog sont pires qu’inutiles : ils sont précis et sûrs d’eux, souvent faux, et l’API ne vous corrigera pas.
Le bug : une ombre est un seul contrôle, pas cinq
Le convertisseur écrivait sept clés pour une ombre — une pour l’activer, puis la couleur, le décalage horizontal, le décalage vertical, le flou, l’expansion et la position comme valeurs séparées. Cela a l’air rigoureux. C’était presque entièrement faux.
Le groupe box-shadow enregistre exactement deux champs. L’ombre elle-même est un seul contrôle composite dont la valeur est un objet unique contenant ensemble le décalage horizontal, le décalage vertical, le flou, l’expansion et la couleur ; le second champ est la position outline/inset. Ajoutez l’interrupteur du popover et l’ensemble réel de clés compte trois noms, tous préfixés deux fois parce que le groupe lui-même est nommé box_shadow.
Sur les sept clés écrites, cinq n’existaient pas. La sixième avait le bon nom mais recevait la chaîne "yes" au lieu de l’objet qu’elle attend. La septième était proche mais il lui manquait un préfixe.
Un détail qu’aucune conjecture n’aurait permis de deviner : la valeur pour « Outline » est un seul espace, pas une chaîne vide. Cela se trouve dans le tableau d’options et nulle part ailleurs.
Le second bug : le bon nom qui ne faisait toujours rien
La même revue a fait apparaître flex_grow et flex_shrink, écrits sur des éléments ayant une largeur explicite pour empêcher un parent flex de les étirer ou de les comprimer. Encore faux — ces contrôles se trouvent dans un groupe enregistré sous un autre nom, il leur fallait donc un préfixe.
Mais corriger le préfixe n’aurait toujours pas fonctionné, et c’est ce qu’il faut retenir. Les deux champs portent une condition : ils ne s’appliquent que lorsque le contrôle de taille du groupe est réglé sur « custom ». Les conditions régissent la génération CSS, pas seulement la visibilité dans le panneau. Un nom de clé correct est nécessaire, mais pas suffisant.
La véritable correction s’est avérée plus simple que les deux tentatives, et elle se trouvait dans le code source depuis le début : le contrôle de taille possède une option « none » qui signifie exactement « ne pas grandir, ne pas rétrécir » — un seul contrôle inconditionnel au lieu de trois contrôles conditionnels. Lire le code source n’a pas seulement corrigé le bug, cela a produit une meilleure implémentation que celle qui était visée.
Auditer le reste
Deux bugs trouvés par la lecture. Il restait environ quatre-vingt-dix autres clés que personne n’avait lues. L’étape suivante était donc mécanique : analyser le code source officiel du plugin, construire l’ensemble faisant autorité des noms de contrôles pour chaque widget, et le comparer à chaque clé que le convertisseur peut émettre.
Le script d’audit a donné quatre mauvaises réponses avant d’en donner une bonne. Chacun de ces échecs a une portée générale :
- Le nom est souvent sur la ligne suivante. Les enregistrements de contrôles placent souvent le nom sur la ligne qui suit l’appel. Un motif ne couvrant qu’une seule ligne les manquait, et chaque widget semblait émettre cinq clés invalides — tout l’onglet Avancé. Un vérificateur qui signale un contrôle standard comme inconnu ne signale pas un bug, il signale son propre angle mort.
- Deux idiomes pour la même chose. Un groupe construit ses champs sous un nom de variable, un autre en utilise un différent. Ne reconnaître que le premier faisait disparaître silencieusement des groupes entiers — y compris, non sans ironie, précisément le groupe sur lequel portait l’enquête.
- Les tableaux d’arguments s’imbriquent. Arrêter la correspondance au premier crochet fermant tronquait au premier tableau imbriqué et sautait entièrement l’enregistrement. C’est ainsi que plusieurs clés de mise en page parfaitement valides sont d’abord apparues comme « invalides ».
- Une fenêtre de capture large avale tout. Corriger le point précédent en prenant une grande fenêtre signifiait que chaque correspondance engloutissait tous les enregistrements qu’elle contenait. Le nombre de contrôles connus d’un widget est tombé de 281 à 60 et la comparaison signalait toujours un succès.
Et un de plus, propre à cette base de code : le fichier du widget Bouton ne contient aucun enregistrement de contrôle. Ils se trouvent tous dans un trait. La première exécution a indiqué que Bouton n’avait aucun contrôle.
Remarquez le sens de ces erreurs. Trois ont produit de fausses alarmes — agaçantes, mais autocorrectives : vous enquêtez et découvrez que l’outil a tort. Une a produit un faux succès, et c’est là le type d’erreur dangereux. Moins de noms valides connus signifie moins de problèmes signalés ; le mode de défaillance est silencieux et rassurant.
La vérification qui rend les autres fiables
Ce qui mène à la seule idée à retenir de tout l’exercice.
Un vérificateur qui annonce « tout est propre » ne vaut rien tant que vous n’avez pas prouvé qu’il est capable d’annoncer « pas propre ».
L’audit se termine donc par un contrôle négatif : il réinjecte les cinq noms de clés connus comme mauvais et fait échouer toute l’exécution si l’un d’eux est accepté. Si l’extracteur casse plus tard — un motif élargi, un fichier sauté, un mauvais cache — cette assertion passe au rouge avant que la ligne « tout a réussi » n’ait l’occasion de mentir.
Deux points d’ancrage supplémentaires l’accompagnent : une liste de noms de contrôles dont l’existence est certaine doit être entièrement retrouvée, et le nombre total ne doit jamais diminuer silencieusement. C’est ce second point qui aurait détecté l’effondrement de 281 à 60.
Faire en sorte que cela reste corrigé
État final une fois la comparaison revenue propre : 205 clés vérifiées sur neuf types de widgets, aucune inconnue. Ensuite, une tâche d’intégration continue pour que cela reste ainsi — elle convertit une page contenant une ombre et vérifie sur la sortie que la clé composite est présente et qu’aucun des anciens noms séparés n’est revenu.
Pas un test unitaire d’une fonction pure. Une assertion sur l’artefact réellement livré, vérifiant l’erreur exacte qui s’est déjà produite une fois.
La version générale
Si vous écrivez dans n’importe quel système qui ignore les clés inconnues — un constructeur de pages, une table meta de CMS, les données envoyées à un outil d’analytics, un blob de feature flags, la moitié des formats de configuration existants — alors :
- Déduisez l’ensemble des clés valides à partir de la source de vérité, pas de la mémoire ou de la documentation. La documentation décrit l’intention ; les noms générés n’existent qu’à l’exécution.
- Faites un diff mécanique entre ce que vous émettez et cet ensemble. Quatre-vingt-dix clés ne sont pas vérifiables à l’œil nu, et les mauvaises ressemblent exactement aux bonnes.
- Méfiez-vous d’abord de votre vérificateur. Quand une exécution signale quelque chose dont vous êtes sûr, l’outil a tort bien plus souvent que le code.
- Ajoutez un contrôle négatif. Prouvez que le vérificateur peut échouer, sinon ses succès ne signifient rien.
- Faites une assertion sur l’artefact livré en CI, car cette classe de bug revient dès que quelqu’un refactorise le code émetteur.
Les ombres fonctionnent maintenant. L’enseignement le plus utile a été de constater que l’absence d’erreur avait été tenue pendant des mois pour une preuve d’exactitude, sur une API structurellement incapable d’en produire une.