Aller au contenu

PHPStan

L’extension blockstudio/phpstan apporte l’analyse statique aux projets Blockstudio. Elle valide les modèles de blocs, les fichiers de schéma, les chemins des réglages et les noms de hooks au moment de l’analyse, afin de détecter les bugs avant leur apparition à l’exécution.

Installation

Shell
composer require --dev blockstudio/phpstan

Le typage des modèles de la version 7.7 et les vérifications étendues des balises de bloc nécessitent blockstudio/phpstan 0.1.9 ou une version ultérieure, ainsi que PHPStan 2.1.47 ou une version ultérieure. Mettez à jour le paquet séparément de l’extension :

Shell
composer require --dev blockstudio/phpstan:^0.1.9

L’extension est détectée automatiquement par l’installateur d’extensions de PHPStan. Aucune configuration manuelle n’est nécessaire.

Vérifications effectuées

Accès aux champs des modèles

Lorsqu’un fichier PHP se trouve à côté d’un block.json, l’extension valide chaque accès $a['key'] par rapport aux attributs déclarés du bloc.

PHP
<?php

echo $a['title'];     // OK
echo $a['subtitle'];  // OK
echo $a['typo'];      // Error: Field "typo" does not exist in block.json

L’extension sait que Blockstudio définit $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview et les variables d’îlot avant d’inclure un modèle. Les lectures directes telles que $a['title'] ne sont donc pas signalées comme potentiellement non définies, et le type de $a est déduit du block.json associé au modèle. Cette structure est conservée lors de la réduction de type, de sorte que $a['label'] ?? '', isset( $a['cta']['target'] ) et $a['cta']['title'] !== null gardent les types de champs déclarés ; un modèle qui affecte une valeur à $a conserve le type qu’il lui a attribué. N’ajoutez pas de docblock /** @var array<string, mixed> $a */ : il remplace cette structure par un tableau ouvert.

Les clés des champs suivent les règles d’aplatissement à l’exécution de Blockstudio. tabs et les conteneurs group anonymes sans id servent uniquement à la présentation : leurs champs enfants restent dans l’espace de noms parent. Un groupe nommé préfixe ses clés enfants avec son ID :

PHP
echo $a['heading'];  // Anonymous group child.
echo $a['cta_text']; // "text" inside the named "cta" group.

Champs personnalisés réutilisables

Les références custom/* basées sur des fichiers sont développées avant la vérification des clés de modèles et des structures de tableaux. L’extension lit le field.json correspondant et applique les mêmes règles de idStructure, overrides, de référence imbriquée, de groupe, d’onglets et de répéteur que Blockstudio :

JSON
{
  "name": "mytheme/hero",
  "attributes": [
    { "id": "heading", "type": "text" },
    { "id": "description", "type": "textarea" }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "custom/mytheme/hero",
        "idStructure": "hero_{id}",
        "overrides": {
          "heading": { "id": "title" }
        }
      }
    ]
  }
}

Les clés de modèles obtenues sont title et hero_description. Elles sont reconnues dans PHP, Twig, Blade, les balises de bloc et les structures d’attributs déduites.

Les définitions basées sur des fichiers manquantes, ambiguës, non valides ou cycliques génèrent une erreur blockstudio.customField.* précise. Les vérifications des clés dépendantes sont ignorées pour ce bloc afin qu’une définition non résolue ne génère pas une nouvelle série de fausses erreurs de champs inconnus.

Les définitions enregistrées uniquement à l’exécution via le filtre blockstudio/fields PHP ne peuvent pas être déduites par l’analyse statique. Utilisez une définition field.json si le champ doit fournir des clés de modèles vérifiées statiquement.

Accès aux modèles Twig

Les modèles Twig sont analysés automatiquement. Aucune annotation n’est nécessaire.

Twig
<h1>{{ a.title }}</h1>
<p>{{ a.typo }}</p>    {# Error: Field "typo" does not exist in block.json #}

Accès aux modèles Blade

Les modèles Blade sont analysés de la même manière.

Blade
<h1>{{ $a['title'] }}</h1>
<p>{{ $a['typo'] }}</p>    {{-- Error --}}

Validation des balises de bloc

Les balises de bloc sont validées là où Blockstudio les lit : les balises <bs:> et <block>, les balises à préfixe configurées dans blockTags.prefixes (comme <acme-card>, résolues par ordre d’espace de noms comme à l’exécution) et les balises alias, dans les modèles de blocs PHP, Twig et Blade, ainsi que dans les mises en page. Les sources de pages sous pages/ (index.php, index.html, index.twig, index.blade.php) sont également vérifiées, y compris les éléments HTML que le projet associe à des blocs. Les blocs UI intégrés sont reconnus lorsque ui.enabled est activé.

HTML
<bs:mytheme-hero title="Hello" />
<!-- OK -->
<bs:mytheme-nonexistent />
<!-- Error: unknown block -->
<bs:mytheme-hero title="Hi" badattr="" />
<!-- Error: unknown attribute -->
<bs:mytheme-hero class="wide" />
<!-- Error: class is dropped unless the block declares a class field -->
<bs:mytheme-hero id="intro" aria-label="Intro" data-x="1" />
<!-- OK: forwarded to the root element -->
<block name="core/separator" />
<!-- OK (core blocks always valid) -->

Un attribut est accepté si le bloc le déclare comme champ (y compris les champs personnalisés et ceux qu’un champ typé comme bloc transmet sous son idStructure), ou si Blockstudio le transmet à l’élément racine du bloc : data-*, aria-*, id, style, role, title, lang, dir, hidden et tabindex. Dans les modèles, tous les attributs html-* sont transmis ; dans les sources de pages, un préfixe html- ne désigne que l’un des attributs transmis. Tout autre attribut, surtout un class non déclaré, est signalé, car Blockstudio le stocke sans jamais l’afficher.

À l’exécution, les filtres PHP enregistrent les correspondances entre éléments et balises alias, que l’analyse statique ne peut pas évaluer ; celle-ci les lit donc depuis blockstudio.json. scanPhp vérifie également les balises dans d’autres fichiers PHP du projet, comme le balisage des composants dans les modules, sans y signaler de blocs inconnus :

JSON
{
  "phpstan": {
    "blockTags": {
      "elements": {
        "section": "theme/section",
        "h2": "theme/heading",
        "div": [
          { "attribute": "width", "block": "theme/row" },
          "theme/div"
        ]
      },
      "aliases": { "theme-button": "bsui/button" },
      "scanPhp": true
    }
  }
}

Un élément correspond à un nom de bloc ou à des règles testées dans l’ordre : la première règle dont l’attribut est présent sur l’élément s’applique, et un simple nom de bloc correspond toujours. Les éléments qu’un projet n’associe pas conservent leur bloc principal et ne sont pas vérifiés. Les diagnostics utilisent blockstudio.blockTag.unknown, blockstudio.blockTag.attribute et blockstudio.blockTag.class.

Typage des enregistrements de base de données

Db::get() renvoie une instance typée en fonction du schéma db.php. La structure des enregistrements est déduite automatiquement.

PHP
return [
    'storage' => 'table',
    'fields' => [
        'email' => ['type' => 'string', 'required' => true],
        'name'  => ['type' => 'string'],
    ],
];
PHP
$db = Db::get('mytheme/subscribers');
$record = $db->create(['email' => 'a@b.com']);

echo $record['email']; // string
echo $record['name'];  // string|null (optional field)
echo $record['typo'];  // Error: Offset 'typo' does not exist

Les champs obligatoires ne peuvent pas être nuls. Les champs facultatifs sont type|null. Un champ id (int) est toujours présent. Le même typage fonctionne avec la syntaxe de création Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field native à PHP.

Validation des chemins de réglages

Les chemins Settings::get() sont vérifiés par rapport au schéma de réglages connu.

PHP
Settings::get('tailwind/enabled');  // OK, returns bool
Settings::get('tailwind/enabld');   // Error: Did you mean "tailwind/enabled"?

Validation des noms de hooks

Les noms des hooks de filtre et d’action Blockstudio sont validés.

PHP
add_filter('blockstudio/render', $cb);   // OK
add_filter('blockstudio/rendrr', $cb);   // Error: Did you mean "blockstudio/render"?

Les hooks de réglages dynamiques comme blockstudio/settings/tailwind/enabled sont toujours autorisés. Les hooks qui ne viennent pas de blockstudio sont ignorés.

Validation des schémas

L’extension valide chaque fichier de schéma Blockstudio du projet.

block.json:

  • Champ name manquant
  • Champ type manquant
  • id manquant pour les champs de valeur qui en nécessitent un
  • Types de champ inconnus
  • Propriétés de champ non acceptées par le type de champ, par exemple "translat" au lieu de "translate" ; la propriété connue la plus proche est suggérée
  • select/radio/checkbox sans options ni populate
  • Identifiants de champ en double
  • Champ tabs dans un répéteur, directement ou dans un groupe sans id
  • Déclarations pluginDependencies invalides

Les champs conteneurs comme group et tabs, ainsi que les références aux champs custom/*, peuvent omettre id lorsqu’ils ne font qu’ajouter ou envelopper d’autres champs.

Les propriétés des champs sont vérifiées par rapport aux propriétés schemas/block.json déclarées pour chaque type de champ intégré, ainsi qu’aux propriétés acceptées par tous les champs. Les propriétés propres aux wrappers des références custom/* et les types de champs avec espace de noms définis par le projet ne sont pas concernés par cette vérification. La validation existante des types de champs et des références personnalisées reste applicable. Les identifiants sont blockstudio.blockJson.property et blockstudio.fieldJson.property.

Cette vérification porte sur les noms des propriétés, et pas seulement sur leurs valeurs : minimized est valide sur un répéteur, mais signalé sur un champ de texte. Le comportement du plugin à l’exécution reste inchangé. Si un projet associe délibérément ses propres métadonnées aux champs intégrés, supprimez uniquement ces signalements sans désactiver les autres vérifications de structure :

Neon
parameters:
    ignoreErrors:
        - identifier: blockstudio.blockJson.property
        - identifier: blockstudio.fieldJson.property

Les champs intégrés d’un field.json réutilisable sont toujours vérifiés, même lorsqu’une référence custom/* possède ses propres options de wrapper. Les fichiers d’extension ne sont pas concernés par ces diagnostics de nom de propriété ; les règles set propres aux extensions restent valides.

field.json (champs personnalisés réutilisables) :

  • name manquant
  • attributes manquant ou vide
  • Objets d’attribut invalides ou type de champ manquant
  • id manquant pour les champs de valeur qui en nécessitent un
  • Types de champs inconnus
  • Propriétés de champ non acceptées par le type de champ
  • Champ tabs dans un répéteur, directement ou dans un groupe sans id
  • Références custom/* imbriquées manquantes, ambiguës, invalides ou cycliques

Extension JSON (extensions de blocs dans extensions/) :

  • name manquant (bloc cible)
  • Clé blockstudio manquante
  • Clé blockstudio.extend manquante

page.json (pages basées sur des fichiers) :

  • title manquant
  • slug manquant
  • Valeurs postStatus non valides

db.php:

  • Tableau fields manquant
  • Types de champs non valides
  • Prend en charge les tableaux hérités et Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field

rpc.php:

  • Méthodes HTTP non valides
  • Valeur public incorrecte (doit être true, false ou 'open')
  • Prend en charge les tableaux hérités et les retours d’objets avec attributs

cron.php:

  • schedule manquant pour les tâches configurées
  • callback manquant pour les tâches configurées
  • Prend en charge les tableaux hérités et les retours d’objets avec attributs

blockstudio.json:

  • Booléens abrégés tels que "tailwind": true (doit utiliser le format d’objet imbriqué {"enabled": true, "config": ""})

Configuration

L’extension détecte par défaut les fichiers Blockstudio dans le projet analysé. Lorsqu’un projet utilise des blocs ou des champs réutilisables provenant d’une bibliothèque située en dehors de la racine du projet, ajoutez le chemin de la bibliothèque à blockstudioScanRoots. Ce chemin est analysé à la recherche des définitions block.json et field.json, afin que les balises de blocs externes et leurs champs personnalisés puissent être validés ensemble.

YAML
parameters:
  blockstudioScanRoots:
    - vendor/acme/block-library/blockstudio

Pour ignorer des fichiers, utilisez la configuration standard excludePaths de PHPStan.

Préréglages d’analyse

L’extension détectée automatiquement reste la base qui assure la compatibilité. Blockstudio 7.6 ajoute des couches facultatives sans modifier les projets existants :

Préréglage Comportement
base.neon Analyse existante du schéma, des modèles, des hooks, des réglages et de API.
theme.neon Base, avec les racines de thème WordPress, les en-têtes de style, les ressources Blockstudio, le ciblage des sélecteurs, les valeurs par défaut des champs et les limites des répétiteurs.
extreme-theme.neon Thème, avec PHPStan max, les PHP non sécurisés, l’échappement de sortie, Tailwind, JavaScript et les vérifications d’interactivité API.
wordpress-render.neon Thème extrême, avec une sonde de rendu WordPress en direct fournie par l’appelant.

L’installation de blockstudio/phpstan active uniquement l’extension de base. Incluez une couche facultative dans une configuration PHPStan existante :

YAML
includes:
  - vendor/blockstudio/phpstan/extreme-theme.neon

parameters:
  blockstudioThemeRoots:
    - .
  blockstudioThemeExcludePaths:
    - fixtures/**
  blockstudioThemeMaxFiles: 10000
  blockstudioExtremeJavaScript: true
  blockstudioExtremeTailwind: true

blockstudioThemeExcludePaths contrôle l’analyseur de thèmes. La configuration excludePaths standard de PHPStan contrôle séparément l’analyse de PHP.

Le réglage phpstan.excludePaths de la commande canonique dans blockstudio.json (et son option --exclude) configure les deux couches. Les motifs relatifs sont résolus par rapport à chaque racine configurée ; ainsi, les entrées comme vendor/** limitent l’analyse de PHPStan ainsi que l’analyse du projet par Blockstudio.

Un motif désignant un seul répertoire, comme _dist/** ou node_modules/**, exclut ce répertoire où qu’il se trouve, et pas seulement à côté de la racine du thème. Un motif contenant une barre oblique, comme assets/*/docs/**, reste ancré à la racine. Les ressources de blocs générées se trouvent dans un répertoire _dist à l’intérieur de chaque bloc ; la forme à répertoire unique permet donc d’exclure les fichiers compilés de l’analyse.

Commande canonique

Le paquet installe vendor/bin/blockstudio-phpstan comme exécutable d’analyse. Il utilise le préréglage base, sauf si le projet en choisit un autre. L’installation du paquet n’active donc pas à elle seule les couches thème ou thème extrême :

Shell
vendor/bin/blockstudio-phpstan --root . -- --no-progress

Les préréglages incluent eux-mêmes l’extension. N’ajoutez pas phpstan/extension-installer à un projet qui exécute la commande canonique : lorsque l’installateur est présent, extension.neon est chargé deux fois et PHPStan s’arrête avec « Ce fichier est inclus plusieurs fois » avant toute analyse.

Par défaut, la commande définit PHPStan sur une limite mémoire 1G afin que les projets WordPress gérés par Composer ne soient pas soumis à la limite habituelle de 128M CLI. Ajoutez une option PHPStan explicite après -- pour la remplacer, par exemple -- --memory-limit=512M --no-progress.

Adopter l’analyse dans un projet existant

Un projet qui n’a jamais été analysé signalera généralement des problèmes lors de sa première analyse. Au lieu d’abaisser le préréglage, générez une référence PHPStan et indiquez à phpstan.configuration un fichier de configuration du projet qui l’inclut. Le nouveau code sera alors soumis au préréglage complet, tandis que les problèmes déjà consignés ne gêneront pas l’analyse :

Shell
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
Neon
includes:
    - phpstan-baseline.neon

parameters:
    level: max
JSON
{
  "phpstan": {
    "configuration": "phpstan.neon"
  }
}

Conservez la ligne level pour les préréglages base et theme. La commande canonique ne définit le niveau max pour ces préréglages que si aucune configuration du projet n’est incluse ; sans niveau, PHPStan s’arrête avec « Aucune règle détectée ». Le préréglage extreme-theme définit lui-même le niveau max.

Les chemins relatifs sont résolus à partir de blockstudio.json. La commande canonique et le hook de commit géré détectent tous deux ce fichier. Le hook bloque ainsi les nouveaux problèmes sans exiger que ceux déjà présents soient d’abord corrigés.

Conservez les valeurs par défaut des commandes pour l’ensemble du projet dans blockstudio.json :

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "phpstan": {
    "preset": "extreme-theme",
    "roots": ["."],
    "excludePaths": ["fixtures/**"],
    "maxFiles": 10000
  }
}

Les racines relatives sont résolues à partir du fichier qui les déclare. Les valeurs CLI explicites remplacent les valeurs JSON correspondantes. Transmettez --blockstudio-json path/to/project.json pour choisir une autre source de configuration. Les fichiers JSON mal formés, les clés phpstan non prises en charge, les valeurs non valides et l’absence d’une source explicite provoquent tous un échec déterministe avec le code de sortie 2.

Choisissez un autre préréglage, incluez une configuration de projet, ajoutez des racines et des exclusions répétables, ou demandez à PHPStan de JSON :

Shell
vendor/bin/blockstudio-phpstan \
  --preset theme \
  --configuration phpstan.neon \
  --root . \
  --exclude 'fixtures/**' \
  --max-files 10000 \
  --error-format json \
  -- --no-progress

Le wrapper compose la configuration dans le répertoire temporaire du système et la supprime à la fin. Il n’écrit jamais de configuration générée, de références, de hooks ni de caches dans le projet analysé. Les appelants peuvent toutefois configurer explicitement le cache normal de PHPStan.

Le contrat de sortie est le suivant :

  • 0 si l’analyse réussit
  • 1 si PHPStan signale des diagnostics
  • 2 en cas d’utilisation ou de configuration non valide, ou d’échec d’exécution du processus

Hook de commit géré

Pour faire de l’analyse de thème extrême une condition de validation des commits du dépôt, activez le hook géré par Blockstudio dans blockstudio.json :

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "phpstan": {
    "preset": "extreme-theme",
    "roots": ["."],
    "excludePaths": [],
    "maxFiles": 10000
  },
  "githooks": {
    "commit": true
  }
}

Synchronisez-le après l’installation des dépendances ou la modification du réglage :

Shell
vendor/bin/blockstudio-githooks sync

La commande écrit le hook pre-commit généré et son enregistrement de propriété dans le répertoire commun de Git, définit core.hooksPath sur le répertoire des hooks gérés et enchaîne en toute sécurité avec le hook pre-commit précédemment configuré. Les synchronisations répétées ne mettent à jour que le fichier généré ; les mises à niveau du paquet sont donc idempotentes.

Définissez commit sur false, supprimez-le, ou supprimez blockstudio.json, puis exécutez sync pour restaurer le chemin de hook enregistré et supprimer uniquement les fichiers appartenant à Blockstudio. Vous pouvez aussi exécuter :

Shell
vendor/bin/blockstudio-githooks remove

Les fichiers appartenant aux utilisateurs ne sont jamais écrasés ni supprimés. Si quelqu’un modifie core.hooksPath après l’activation de Blockstudio, la suppression préserve ce réglage plus récent. Le hook généré prend en charge les extractions Git liées et les chemins contenant des espaces, en résolvant le dépôt actif et la racine du projet au moment du commit. Il exécute la commande canonique depuis cette racine ; le même objet phpstan contrôle ainsi les analyses interactives et les commits, sans arguments générés en double.

Le hook exécute uniquement vendor/bin/blockstudio-phpstan. Blockstudio n’exécute pas de formateur et le hook ne réécrit jamais les fichiers du projet. Les dépendances manquantes et les échecs d’analyse bloquent le commit avec un message d’erreur indiquant comment résoudre le problème.

Rendu WordPress en direct

La couche en direct est volontairement explicite. L’appelant gère l’environnement WordPress et fournit un tableau argv :

Shell
vendor/bin/blockstudio-phpstan \
  --preset wordpress-render \
  --render-command='["wp","eval-file","tools/render-probe.php"]' \
  --render-working-directory=. \
  --render-timeout=60 \
  --root .

La commande s’exécute sans shell et doit afficher un objet JSON :

JSON
{"ok":true}

Une sonde peut signaler un échec précis :

JSON
{
  "ok": false,
  "message": "Rendered block failed.",
  "file": "/absolute/path/to/block.json",
  "line": 12
}

Les codes de sortie différents de zéro, les délais d’attente dépassés, les données JSON mal formées et ok: false produisent blockstudio.wordpress.render.

blockstudio.javascript.domContract signale un sélecteur d’attribut [data-*] qu’un script transmet à querySelector(), querySelectorAll(), closest() ou matches() alors qu’aucun balisage analysé ne porte cet attribut. Le balisage comprend tous les fichiers PHP, Twig, Blade et HTML, ainsi que tous les composants React .tsx et .jsx situés sous les racines analysées, à l’exception des chemins exclus. Les composants sont analysés : les noms d’attributs JSX sont pris en compte, tout comme les clés de chaîne des littéraux d’objet. Ainsi, un objet d’attributs appliqué à un élément par propagation satisfait le sélecteur, tandis que les noms de classes et les autres valeurs d’attribut ne le satisfont pas.

Les vérifications d’interactivité API analysent les mêmes composants React. Un espace de noms data-wp-interactive sur un élément JSX compte comme référence de modèle pour blockstudio.interactivity.orphan, et les directives data-wp-* qu’il contient sont résolues par rapport à l’espace de noms englobant le plus proche, ou à un préfixe namespace:: dans la valeur. Les directives dont la valeur est une chaîne statique, écrites sous forme d’attribut JSX ou de clé de chaîne dans un objet d’attributs, doivent désigner des gestionnaires et chemins existants dans le magasin (blockstudio.interactivity.handler, blockstudio.interactivity.binding), et le code du magasin ne doit pas modifier les attributs ni les classes auxquels ils sont liés (blockstudio.interactivity.derivedState). React échappe les valeurs d’attribut ; data-wp-context dans un composant ne génère donc aucun signalement, et les valeurs dynamiques ne sont pas vérifiées. Les espaces de noms sous bsui/ appartiennent aux blocs UI inclus, dont les magasins sont fournis avec Blockstudio en dehors des racines analysées ; ils ne sont donc jamais orphelins.

Identifiants de diagnostic

Les nouveaux diagnostics des préréglages conservent des identifiants blockstudio.* stables :

  • Structure du thème : blockstudio.theme.root.missing, blockstudio.theme.style.missing, blockstudio.theme.style.header, blockstudio.theme.scanLimit
  • Ressources et champs : blockstudio.theme.asset.manualEnqueue, blockstudio.theme.asset.selectorScope, blockstudio.theme.asset.missing, blockstudio.field.default, blockstudio.field.repeaterBounds
  • PHP : blockstudio.php.forbiddenFunction, blockstudio.wordpress.rawDatabaseWrite, blockstudio.output.unescaped
  • Tailwind : blockstudio.tailwind.compilerMissing, blockstudio.tailwind.compile, blockstudio.tailwind.unknownUtility, blockstudio.tailwind.semanticToken
  • JavaScript : blockstudio.javascript.syntax, blockstudio.javascript.debugOutput, blockstudio.javascript.bannedApi, blockstudio.javascript.leakedGlobal, blockstudio.javascript.importSpecifier, blockstudio.javascript.rootGuard, blockstudio.javascript.initShape, blockstudio.javascript.domContract, blockstudio.javascript.listenerCleanup, blockstudio.javascript.reducedMotion
  • Interactivité : blockstudio.interactivity.import, blockstudio.interactivity.moduleImport, blockstudio.interactivity.namespace, blockstudio.interactivity.scopedDom, blockstudio.interactivity.derivedState, blockstudio.interactivity.handler, blockstudio.interactivity.binding, blockstudio.interactivity.context, blockstudio.interactivity.orphan

Performances

L’analyseur accepte les répertoires matérialisés courants, élimine les doublons parmi les racines, ignore les arborescences de dépendances, de compilation et de cache, met en cache les lectures de fichiers en mémoire et trie les diagnostics de façon déterministe. Limitez les racines, excluez les arborescences de tests et les fichiers générés, et fixez une limite de fichiers pour les grands dépôts. JavaScript et Tailwind peuvent être désactivés indépendamment. Le rendu en direct ne s’exécute que si son préréglage est sélectionné.

Les diagnostics de thème, JavaScript et Tailwind sont signalés via le cache de résultats de PHPStan. Après la modification d’un seul block.json ou d’un script, un cache encore actif peut renvoyer le résultat précédent. Ajoutez --debug après -- pour ignorer le cache lors de la vérification de telles modifications.

Contrat de projet pour les agents de programmation

Le paquet installe un troisième exécutable, vendor/bin/blockstudio-agents. Il génère un fichier AGENTS.md décrivant le projet dans lequel il s’exécute. Un agent de programmation en a besoin avant de modifier quoi que ce soit : quels éléments le projet crée, quelles fonctionnalités Blockstudio sont activées, ce que l’analyse rejettera et quelles commandes utiliser.

Shell
vendor/bin/blockstudio-agents
Text
Blockstudio contract created: /path/to/project/AGENTS.md

Aucune ligne de la sortie ne provient d’un modèle fixe. Chacune est tirée de l’une de ces trois sources :

  • Les propres fichiers du projet. Un thème avec un en-tête style.css, des blocs et des pages définies par des fichiers produit un document différent de celui d’un plug-in qui ne fait qu’enregistrer des blocs. Les nombres, répertoires, espaces de noms des blocs et langages des modèles proviennent des éléments réellement trouvés par l’analyseur, qui utilise les mêmes racines et exclusions que l’analyse.
  • blockstudio.json. Seules les fonctionnalités activées sont décrites, avec leurs valeurs configurées : préfixes des balises de blocs et espaces de noms qu’ils ciblent, Tailwind, UI intégré, réinitialisation des ressources de l’éditeur, chemin du cache, profil de performance, prérendu statique et chemins dynamiques, valeurs par défaut du thème, synchronisation de contenu et hook de commit.
  • Le préréglage phpstan.preset sélectionné. La section consacrée à la conformité est lue directement dans les fichiers de préréglage, couche par couche, et énumère donc exactement les règles enregistrées par ce préréglage. Avec base, elle décrit les règles relatives aux schémas, modèles, hooks et réglages. Avec extreme-theme, elle décrit aussi les règles de structure du thème, les indicateurs PHPStan stricts, les PHP non sécurisés, l’échappement de sortie, Tailwind et JavaScript. Chaque nouvelle règle d’un préréglage est ajoutée au document généré.

La section des commandes suit le même principe. wp bs prerender status apparaît lorsque le prérendu statique est activé, vendor/bin/blockstudio-githooks sync lorsque githooks.commit est défini et wp bs db schemas lorsque le projet possède effectivement un db.php.

Option Comportement
--root <path> Racine du projet (par défaut : répertoire courant)
--config <path> Chemin blockstudio.json (par défaut : <root>/blockstudio.json)
--output <path> Chemin du contrat (par défaut : <root>/AGENTS.md)
--stdout Afficher le contrat au lieu de l’écrire
--check Quitter avec le code 1 si le contrat sur le disque n’est plus à jour
--force Remplacer un fichier dont Blockstudio n’est pas propriétaire

--check permet au contrat de bloquer l’intégration continue, comme le hook de commit bloque l’analyse :

Shell
vendor/bin/blockstudio-agents --check

Propriété

Le fichier généré contient le même type de marqueur que le hook de commit géré, et la même règle s’applique : Blockstudio ne remplace jamais un fichier qu’il n’a pas écrit. Si un AGENTS.md existait avant l’exécution de la commande ou a été créé manuellement, il est préservé et la commande quitte avec le code 2, à moins que l’option --force soit indiquée.

La régénération ne pose pas de problème. Le fichier se termine par une zone de notes, et les octets situés entre ses marqueurs sont conservés à chaque régénération :

Markdown
## Project notes

<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->

Les codes de sortie sont 0 lorsque le contrat est écrit, à jour ou affiché, 1 lorsque --check détecte un contrat obsolète et 2 en cas d’erreur d’utilisation, de configuration ou de système de fichiers.

Formes des types de champ

L’extension associe chaque type de champ Blockstudio à un type PHP concret :

Type de champ Type de PHP
text, textarea, richtext, wysiwyg, code string
date, datetime, classes, html-tag, unit, gradient string
number, range int|float
toggle bool
select, radio, checkbox (unique) string|int
select, checkbox (multiple) list<string|int>
color array{value: string, opacity: float|null}
link array{url: string, title: string|null, target: string|null, opensInNewTab: bool|null}
icon array{set: string, subSet: string, icon: string}
files (unique) array{id: int, url: string, alt: string|null, mime_type: string|null}
files (multiple) list<array{id: int, url: string, ...}>
group Les groupes nommés utilisent des préfixes de soulignement ; les groupes anonymes sont aplatis dans l’espace de noms parent
repeater list<array{...child fields...}>
tabs Aplati dans l’espace de noms parent

Fragments de API

L’extension fournit des fragments pour l’ensemble de l’API public de Blockstudio :

  • bs_render_block(), bs_block_values(), bs_get_group(), bs_get_scoped_class(), bs_db_form(), bs_is_editor(), bs_is_preview(), bs_is_buffering(), bs_strip_render_markers()
  • Db::get(), Db::create(), Db::list(), Db::get_record(), Db::update(), Db::delete()
  • Settings::get(), Settings::get_all()
  • Field_Registry::instance(), Field_Registry::all(), Field_Registry::get()
  • Build::blocks(), Build::extensions(), Build::get_build_dir()

Ils fournissent la saisie semi-automatique et la vérification des types sans que le code source du plug-in Blockstudio soit nécessaire sur votre machine.

Prérequis

  • PHP 8.2+
  • PHPStan 2.1.47+
  • phpstan/extension-installer (recommandé pour la détection automatique)

Le paquet installe automatiquement son fournisseur de compatibilité BC Math. ext-bcmath natif est donc facultatif, y compris pour les nouveaux thèmes générés qui activent les vérifications JavaScript avec le préréglage thème ou thème extrême.