Aller au contenu principal

Dépanner et déboguer les Blueprints

Lorsque vous créez des Blueprints, vous pouvez rencontrer des problèmes. Voici des conseils et des outils pour vous aider à les déboguer :

Vérifier les pièges courants​

  • Requérir wp-load : pour exécuter une fonction PHP de WordPress avec l’étape runPHP, vous devez requérir wp-load.php. La valeur de la clé code doit donc commencer par "<?php require_once('wordpress/wp-load.php'); LE_RESTE_DE_VOTRE_CODE".

Problèmes courants et solutions​

Blueprint non valide après l’ouverture d’un lien​

Si Playground indique Invalid blueprint, lisez le message d’erreur détaillé. Il inclut l’erreur d’analyse JSON sous-jacente lorsqu’elle est disponible.

Si le message indique que l’entrée contient encore des échappements %XX après le décodage, le fragment d’URL a probablement été encodé deux fois. Reconstruisez le lien depuis l’objet Blueprint d’origine et encodez-le une seule fois avec encodeURIComponent(JSON.stringify(blueprint)), ou utilisez Base64. N’encodez pas un fragment qui est déjà encodé.

WP-CLI : erreur lors de l’établissement d’une connexion à la base de données sur les sites montés​

Lorsque vous utilisez wp-cli avec un site Playground monté (par exemple avec --mount-before-install), vous pouvez rencontrer une erreur « Error establishing a database connection ». Cela se produit parce que WordPress Playground charge par défaut l’extension d’intégration de base de données SQLite depuis ses fichiers internes, et non depuis le répertoire monté, ce qui signifie qu’elle n’est pas conservée pour les appels externes à wp-cli.

Pour résoudre ce problème, vous devez installer et configurer explicitement l’extension d’intégration de base de données SQLite dans votre Blueprint.

Solution : ajoutez les étapes suivantes à votre Blueprint :

{
	"plugins": ["sqlite-database-integration"]
}

Exemple d’utilisation :

Pour tester cela localement, combinez le Blueprint avec votre commande Playground CLI :

mkdir wordpress
# Ensure your blueprint with the above steps is saved as, for example, './blueprint.json'
npx @wp-playground/cli server --mount-before-install=wordpress:/wordpress --blueprint=./blueprint.json
cd wordpress
wp post list

Cela garantit que l’extension SQLite est installée correctement et configurée dans votre site WordPress monté, ce qui permet aux commandes wp-cli de fonctionner correctement.

Générateur de Blueprints​

Vous pouvez utiliser un éditeur de Blueprints dans le navigateur pour créer, valider et prévisualiser vos Blueprints.

Attention

L’éditeur est en cours de développement et le Playground intégré ne se charge pas toujours. Pour contourner le problème, actualisez la page. Nous en sommes conscients et travaillons à améliorer l’expérience.

Vérifier le système de fichiers et la base de données​

Certaines étapes de Blueprint (comme writeFile) modifient la structure interne du système de fichiers de l’instance Playground, et d’autres (comme runSql) modifient la base de données WordPress interne.

Pour vérifier la structure finale du système de fichiers interne et de la base de données (après l’application des étapes du Blueprint), nous pouvons utiliser des extensions WordPress qui fournissent un gestionnaire SQL et un explorateur de fichiers, comme SQL Buddy et WPide (vous pouvez les voir en action depuis https://playground.wordpress.net/?plugin=sql-buddy&plugin=wpide).

astuce

Plusieurs méthodes peuvent être lancées depuis la console de n’importe quelle instance WordPress Playground pour en inspecter les éléments internes. Elles sont exposées dans l’objet window.playground (voir Développeurs > API JavaScript > Débogage et tests). Quelques exemples :

> await playground.isDir("/wordpress/wp-content/plugins")
true
> await playground.listFiles("/wordpress/wp-content/plugins")
(3) ['hello.php', 'index.php', 'WordPress-Importer-master']

La liste complète des méthodes que nous pouvons utiliser est disponible ici.

Vérifier les erreurs dans la console du navigateur​

Si votre Blueprint ne s’exécute pas comme prévu, ouvrez les outils de développement du navigateur pour vérifier les erreurs.

Pour ouvrir les outils de développement dans Chrome, Firefox, Safari* et Edge : appuyez sur Ctrl + Shift + I sous Windows/Linux ou sur Cmd + Option + I sous macOS.

attention

Si ce n’est pas encore fait, activez le menu Développement : allez dans Safari > Réglages... > Avancé et cochez Afficher les fonctionnalités pour les développeurs web.

La fenêtre des outils de développement vous permet d’inspecter les requêtes réseau, de consulter les journaux de console, de déboguer JavaScript et d’examiner le DOM ainsi que les styles CSS appliqués à votre page. C’est essentiel pour diagnostiquer et corriger les problèmes avec les Blueprints.

Journaliser vos propres messages d’erreur​

Vous pouvez journaliser vos propres messages d’erreur avec error_log via l’étape runPHP (voir l’exemple de Blueprint et la démo en direct) puis les consulter depuis l’option "View Logs" ou depuis la console du navigateur.

Capture des erreurs journalisées

info

Lorsque vous téléchargez votre instance Playground sous forme de zip avec l’option "Download as zip", vous téléchargez aussi le fichier debug.log qui contient tous les journaux de votre instance Playground.

Demander de l’aide​

La communauté est là pour aider. Si vous avez des questions ou des commentaires, ouvrez une nouvelle issue dans ce dépôt. Pensez à inclure les informations suivantes :

  • Le Blueprint que vous essayez d’exécuter.
  • Le message d’erreur que vous voyez, le cas échéant.
  • La sortie complète des outils de développement du navigateur.
  • Toute autre information pertinente qui pourrait nous aider à comprendre le problème : système d’exploitation, version du navigateur, etc.