Modèles vérifiés avec PHPStan et un AGENTS.md généré
Un bloc Blockstudio se compose de deux fichiers qui doivent correspondre. Le block.json déclare les champs et le modèle les lit sous forme de $a['id']. Rien à l’exécution n’empêche le modèle de lire une clé renommée, jamais déclarée ou mal orthographiée. Il génère simplement une chaîne vide, et l’erreur ne devient visible que lorsque quelqu’un remarque un titre vide sur une page en ligne. Il en va de même pour l’échappement de la sortie : un echo non échappé fonctionne parfaitement jusqu’à ce qu’une valeur de champ contienne du balisage.
Le package blockstudio/phpstan déplace ces deux problèmes à l’étape de l’analyse. Il lit vos fichiers block.json, en déduit les types de $a et signale les accès au modèle qui ne correspondent pas. Ses profils prédéfinis facultatifs ajoutent des règles de structure de thème, l’échappement, ainsi que les vérifications JavaScript et Tailwind. Le même package fournit deux outils complémentaires : un hook pre-commit géré qui exécute l’analyse et un générateur qui écrit un AGENTS.md décrivant votre projet pour les agents de programmation.
Ce guide crée un petit thème, casse volontairement l’un de ses modèles, examine le résultat de l’analyse, corrige le problème, puis configure le contrôle des commits et le contrat pour l’agent.
Configurer le thème
Commencez par un dossier de thème contenant un en-tête style.css, un composer.json et un bloc :
acme/
├── blockstudio/
│ └── hero/
│ ├── block.json
│ └── index.php
├── blockstudio.json
├── composer.json
└── style.css
/*
Theme Name: Acme
*/
Installez le package comme dépendance de développement :
composer require --dev blockstudio/phpstan
Il installe PHPStan et les stubs WordPress depuis szepeviktor/phpstan-wordpress, puis installe trois exécutables dans vendor/bin : blockstudio-phpstan, blockstudio-githooks et blockstudio-agents.
Indiquez ensuite à l’analyse quoi exécuter. Les valeurs par défaut du projet se trouvent dans l’objet phpstan de blockstudio.json, afin que les exécutions interactives, la CI et le hook de commit utilisent tous les mêmes paramètres :
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"]
},
"githooks": {
"commit": true
}
}
extreme-theme est le plus strict des trois profils d’analyse statique. Le tableau ci-dessous explique ce que chacun ajoute. excludePaths exclut les propres fichiers de Composer de l’analyse Blockstudio et de l’analyse PHP.
Casser volontairement un modèle
Le bloc hero déclare un seul champ :
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "" }
]
}
}
Le modèle lit correctement ce champ, puis lit un subtitle que le bloc n’a jamais déclaré et l’affiche sans l’échapper :
<section useBlockProps>
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
<p><?php echo $a['subtitle']; ?></p>
</section>
Dans l’éditeur comme sur le site, cela génère un paragraphe vide sans erreur. Lancez plutôt l’analyse :
vendor/bin/blockstudio-phpstan -- --no-progress
------ -------------------------------------------------------------------
Line blockstudio/hero/index.php
------ -------------------------------------------------------------------
2 Variable $a might not be defined.
🪪 variable.undefined
3 Dynamic Blockstudio attributes must be escaped before output.
🪪 blockstudio.output.unescaped
3 Field "subtitle" does not exist in block.json (block: acme/hero).
🪪 blockstudio.field
3 Offset 'subtitle' does not exist on array{heading: string}.
🪪 offsetAccess.notFound
3 Parameter #1 (mixed) of echo cannot be converted to string.
🪪 echo.nonString
3 Variable $a might not be defined.
🪪 variable.undefined
------ -------------------------------------------------------------------
[ERROR] Found 6 errors
La commande se termine avec le code 1. Voici les diagnostics, du plus spécifique au plus général :
blockstudio.fieldest la règle du modèle. Elle a trouvé leblock.jsonà côté du modèle, résolu ses champs et constaté quesubtitlen’en fait pas partie.offsetAccess.notFoundaboutit à la même conclusion en analysant PHPStan lui-même, car l’extension donne à$ala structure concrètearray{heading: string}, déduite deblock.json. Chaque type de champ correspond à un type PHP :textest unstring,toggleunbool, et un répéteur un tableau de structures de lignes.blockstudio.output.unescapedprovient de la coucheextreme-theme. Les valeurs d’attribut affichées doivent passer par une fonction d’échappement telle queesc_html(),esc_attr(),esc_url()ouwp_kses_post().echo.nonStringdécoule de la clé inconnue : un décalage inexistant n’a pas de type chaîne à afficher.variable.undefinedapparaît parce que PHPStan voit un fichier modèle, et non la fonction de rendu qui définit$aavant de l’inclure. La section de correction explique comment résoudre ce problème.
Corriger le problème
Déterminez si subtitle est un vrai champ. C’est le cas ici : déclarez-le avec un default, car la couche du thème en exige un pour chaque champ :
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "" },
{ "id": "subtitle", "type": "textarea", "label": "Subtitle", "default": "" }
]
}
}
Échappez la sortie et déclarez $a avec la structure déduite par l’extension :
<?php
/** @var array{heading: string, subtitle: string} $a */
?>
<section useBlockProps>
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
<p><?php echo esc_html( $a['subtitle'] ); ?></p>
</section>
vendor/bin/blockstudio-phpstan -- --no-progress
[OK] No errors
Rédigez l’annotation en respectant exactement la structure. La commande canonique exécute PHPStan au niveau max ; une annotation @var array<string, mixed> $a moins stricte est rejetée avec varTag.nativeType (« le tag PHPDoc @var de type tableau<string, mixed> n’est pas un sous-type du type natif array{heading: string, subtitle: string} »). Avec la version 7.6, chaque champ est également élargi à mixed, si bien que chaque appel à esc_html() signale argument.type. Le message varTag.nativeType affiche la structure déduite ; c’est aussi le moyen le plus rapide de trouver l’annotation à copier.
Blockstudio 7.7 considère que $a est défini dans les modèles de blocs ; les diagnostics variable.undefined disparaissent donc et l’annotation devient facultative. Avec la version 7.7, le modèle cassé ci-dessus signale quatre erreurs au lieu de six, et le modèle corrigé passe sans la ligne @var.
Choisir un profil
L’installation du package n’active que l’extension de base. La commande canonique exécute base, sauf si le projet sélectionne un autre profil ; l’ajout de la dépendance n’active donc pas à lui seul les couches plus strictes.
| Profil | Ajouts |
|---|---|
base |
Accès aux champs du modèle dans PHP, Twig et Blade, vérifications des balises de bloc, validation des schémas pour block.json, field.json et page.json, extension JSON, db.php, chemins rpc.php et cron.php, ainsi que noms des hooks Settings::get() et blockstudio/*. |
theme |
Base plus racines de thème et en-têtes style.css, ressources déclarées dans block.json au lieu d’être ajoutées manuellement à la file, portée %selector% dans style.scss, valeurs de champ par défaut et limites des répéteurs. |
extreme-theme |
Thème plus indicateurs stricts PHPStan, appels shell et eval() rejetés, écritures $wpdb brutes, échappement de sortie, vérifications Tailwind, JavaScript et API d’Interactivity. |
wordpress-render |
Thème extrême plus une sonde de rendu en direct que vous fournissez sous forme de commande. |
Sans configuration de projet incluse, la commande canonique exécute également base et theme au niveau PHPStan max ; extreme-theme définit lui-même max. Chaque diagnostic de profil possède un identifiant blockstudio.* stable, répertorié dans la référence PHPStan.
Les couches thème et extrême analysent aussi les fichiers PHP. Avec un champ dépourvu de default et un script.js qui écrit dans la console, la même commande signale :
------ -----------------------------------------------------------
Line blockstudio/hero/block.json
------ -----------------------------------------------------------
1 Blockstudio field "subtitle" must define a default value.
🪪 blockstudio.field.default
------ -----------------------------------------------------------
------ ------------------------------------------------------------
Line blockstudio/hero/script.js
------ ------------------------------------------------------------
2 Remove debug output "console.log" from shipped JavaScript.
🪪 blockstudio.javascript.debugOutput
------ ------------------------------------------------------------
Ces vérifications passent par le cache de résultats de PHPStan. Après avoir modifié uniquement un block.json ou un script, un cache chaud peut signaler [OK] No errors pour l’ancien état. Passez --debug après --, ce qui contourne le cache, avant de vous fier à un résultat positif pour des changements qui ne concernent pas PHP :
vendor/bin/blockstudio-phpstan -- --no-progress --debug
Options de commande et codes de sortie
Pour une exécution, les valeurs de la ligne de commande remplacent les valeurs blockstudio.json correspondantes. Il s’agit bien d’un remplacement : passer une valeur --exclude supprime le excludePaths configuré ; répétez donc vendor/** lorsque vous en ajoutez une :
vendor/bin/blockstudio-phpstan \
--preset theme \
--root . \
--exclude 'vendor/**' \
--exclude 'fixtures/**' \
--error-format json \
-- --no-progress
{"totals":{"errors":0,"file_errors":0},"files":{},"errors":[]}
Tout ce qui suit -- est transmis à PHPStan. Le wrapper relève la limite de mémoire de PHPStan à 1G, sauf si vous transmettez votre propre --memory-limit. Il compose sa configuration dans le répertoire temporaire du système, si bien qu’aucun fichier généré n’est placé dans le projet. Il renvoie 0 si l’analyse réussit, 1 si PHPStan signale des diagnostics et 2 en cas d’erreur d’utilisation, de configuration ou d’exécution.
Exécutez-le via la commande canonique au lieu d’ajouter phpstan/extension-installer. Les profils incluent déjà l’extension et, si l’installateur est présent, le même extension.neon est chargé deux fois : PHPStan s’arrête avec le message « Ce fichier est inclus plusieurs fois » avant toute analyse.
L’adopter dans un projet existant
Un projet analysé pour la première fois comporte généralement des problèmes détectés. Au lieu d’assouplir le profil, consignez-les dans une base de référence afin que le nouveau code soit soumis à toutes les règles :
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
[OK] Baseline generated with 3 errors.
Incluez la base de référence dans la configuration du projet et indiquez son chemin à phpstan.configuration :
includes:
- phpstan-baseline.neon
{
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"],
"configuration": "phpstan.neon"
}
}
La prochaine exécution signalera [OK] No errors, avec les problèmes répertoriés pris en compte ; toute nouvelle erreur entraînera toujours un échec. Avec le profil base ou theme, définissez également level: max sous parameters dans phpstan.neon : la commande canonique ne définit elle-même ce niveau que si aucune configuration de projet n’est incluse.
Bloquer les commits en fonction de l’analyse
Avec "githooks": { "commit": true } dans blockstudio.json, synchronisez une fois le hook géré après l’installation des dépendances :
vendor/bin/blockstudio-githooks sync
Blockstudio commit hook enabled: /path/to/acme/.git/blockstudio/hooks/pre-commit
La commande écrit le hook dans le propre répertoire de Git, configure core.hooksPath pour qu’il l’utilise et exécute ensuite tout hook pre-commit configuré auparavant. Le hook lance vendor/bin/blockstudio-phpstan -- --no-progress depuis la racine du projet, et rien d’autre : aucun formateur, aucune réécriture. Un commit contenant le modèle cassé plus haut s’arrête à l’étape de l’analyse :
[ERROR] Found 3 errors
Blockstudio: commit blocked by theme analysis.
Définissez commit sur false, puis relancez sync ou exécutez vendor/bin/blockstudio-githooks remove pour restaurer l’ancien chemin du hook.
Seuls les fichiers créés par Blockstudio sont supprimés.
Générer le contrat du projet
L’analyse indique à l’agent après coup ce qu’il a mal fait. Un AGENTS.md le lui indique à l’avance : où se trouvent les blocs et les pages, comment les champs arrivent dans les modèles, quelles fonctionnalités sont activées et ce que le profil sélectionné refusera.
blockstudio-agents génère ce document à partir du projet lui-même :
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/acme/AGENTS.md
Pour le thème de ce guide, le fichier généré commence ainsi :
# Blockstudio contract for Acme
## Project
- Kind: WordPress theme `Acme`.
- Analysed root: `.`.
- Configuration: `blockstudio.json`.
- Analysis preset: `extreme-theme`.
- Excluded from discovery and analysis: `vendor/**`.
## What this project contains
- Blocks: 1 in `blockstudio`.
- Block namespaces: `acme`.
- Block templates are written in PHP.
Chaque ligne provient de l’une de ces trois sources. Les fichiers du projet fournissent son type, les nombres d’éléments, les répertoires, les espaces de noms et les langages de modèle. blockstudio.json fournit les fonctionnalités activées : le hook de commit figure donc sous « Fonctionnalités activées » et vendor/bin/blockstudio-githooks sync sous « Commandes » uniquement parce que githooks.commit est défini. Le profil sélectionné fournit la section consacrée aux règles de correction, lue dans les fichiers du profil, couche par couche :
The `theme` layer adds:
- Every analysed root must exist and carry a `style.css` with a `Theme Name` header.
- Block assets are declared in `block.json`; block code must not call `wp_enqueue_script()` or `wp_enqueue_style()`.
- A block `style.scss` must scope its rules through `%selector%`, and assets referenced by `block.json` must exist.
- Every field must define a `default`, and repeaters must declare non-negative `min` and `max` bounds.
Le maintenir à jour
Le contrat devient obsolète lorsque la configuration change. Après avoir activé Tailwind dans blockstudio.json, le mode de vérification le détecte :
vendor/bin/blockstudio-agents --check
Blockstudio contract is out of date: /path/to/acme/AGENTS.md
Run blockstudio-agents to regenerate it.
La commande se termine avec le code 1, ce qui permet de l’utiliser comme étape de CI à côté de l’analyse. La régénération ajoute une fonctionnalité « Tailwind CSS » et la commande wp bs tailwind compile.
Notes conservées lors de la régénération
Le fichier se termine par une zone de notes. Tout ce qui se trouve entre ses marqueurs est conservé à l’identique lors de chaque régénération. Les connaissances du projet qui ne peuvent pas être déduites des fichiers doivent donc y figurer :
## Project notes
Everything above is generated. Text between the markers below is preserved when this file is regenerated.
<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->
Le générateur ne remplace jamais un fichier qu’il n’a pas créé. S’il est exécuté sur un AGENTS.md rédigé à la main, il refuse et renvoie le code 2 :
Blockstudio: Refusing to overwrite the user-owned file at /path/to/acme/AGENTS.md. Pass --force to replace it.
Pour conserver le texte rédigé à la main, copiez-le ailleurs, exécutez la commande avec --force, puis collez-le dans la zone de notes. Les autres options sont --root, --config, --output et --stdout, qui affiche le contrat au lieu de l’écrire.
Changements dans Blockstudio 7.7
Le package 7.7 conserve les commandes, les profils et les codes de sortie décrits ici. Deux différences sont apparues lors de la rédaction de ce guide avec cette version : $a ne nécessite plus d’annotation, comme expliqué dans la section de correction, et le contrat généré décrit plus largement la validation des balises de bloc : il couvre les éléments HTML associés à des blocs dans les sources de page ainsi que les attributs globaux qu’une balise peut transmettre.
Étapes suivantes
- PHPStan référence : chaque règle, paramètre prédéfini, forme de type de champ, sonde de rendu en direct et identifiant de diagnostic.
- Intégration de l’IA : l’index de documentation destiné aux agents de programmation, en complément du contrat de votre projet.
- Programmation par vibe avec Blockstudio : travailler avec des agents de programmation sur un projet Blockstudio.
- Recueil de modèles de champs : structures de champs dont l’analyse comprend les clés de modèle, y compris les groupes et les répéteurs.