
Blockstudio La version 7.5 complète le workflow de Blockstudio privilégiant les fichiers : types de champs personnalisés, modèles de l’éditeur de site basés sur des fichiers, îlots de blocs, stockage de base de données Storh, sources de découverte logiques, balises de bloc composables et parcours de déploiement et d’exécution plus rapides.

Les champs personnalisés réutilisables permettent déjà aux projets de définir une fois un groupe de champs existants, puis de le réutiliser avec `type: "custom/{name}"`. Les types de champs personnalisés répondent à un autre besoin. Ils permettent à un thème ou à une extension d’enregistrer un nouveau type de champ avec un espace de noms, de fournir son propre contrôle d’édition et de stocker la valeur sous forme de données Blockstudio standard.

En bref :

- **Sources de découverte logiques** : les environnements d’exécution peuvent fournir un inventaire logique composite des thèmes, avec la provenance et l’identité du cache, tandis que Blockstudio conserve la responsabilité de la découverte, de la résolution des fichiers frères, des ressources générées, de Canvas et du comportement de Tailwind.
- **Registre des types de champs PHP** : les thèmes et les extensions peuvent enregistrer des types de champs avec espace de noms, tels que `acme/dimensions` avec `bs_register_field_type()` ou le filtre `blockstudio/field_types`.
- **Registre des contrôles de l’éditeur** : les scripts d’éditeur personnalisés peuvent appeler `window.blockstudio.registerFieldType()` et afficher le contrôle React correspondant dans le Blockstudio habituel du champ UI.
- **Valeurs structurées** : les champs personnalisés peuvent stocker des chaînes, des nombres, des booléens, des tableaux ou des objets sans convertir les valeurs objet via la normalisation des champs d’option.
- **Prise en charge du stockage** : les champs personnalisés des métadonnées d’articles et ceux liés aux options peuvent déclarer leur type de valeur et leur schéma REST, y compris pour les valeurs objet et tableau.
- **Intégration native** : les types de champs personnalisés fonctionnent dans les groupes, les onglets, les répéteurs, les champs personnalisés réutilisables, les modèles et les chemins de modèles d’extension.
- **Modèles de l’éditeur de site** : les thèmes peuvent définir des sources `wp_template` et `wp_template_part` à partir de fichiers de modèles `template.json`, `part.json` et Blockstudio.
- **Îlots de blocs** : les blocs peuvent d’abord afficher une structure compatible avec le cache, puis hydrater ou récupérer par lot les fragments propres à la requête après le chargement de la page.
- **Stockage de base de données Storh** : `bs.db` peut utiliser dans les téléversements un stockage indexé avec un fichier par enregistrement, tout en préservant les identifiants entiers publics et la migration de JSONC vers Storh via WP-CLI.
- **Améliorations de l’analyseur et de bsui** : les paragraphes richtext mappés nécessitent moins de code d’analyseur personnalisé, `InnerBlocks` peut utiliser `allowedBlocks` tokenisé, la sortie imbriquée de `bs_render_block()` correspond au rendu frontend dans les aperçus de l’éditeur, et `bsui/button` gagne des icônes et des points d’accroche de style plus faciles à utiliser.
- **Balises de blocs composables** : les balises préfixées peuvent être résolues via un autre préfixe (`<theme-ui-input>` vers `bsui/input`), et les balises préfixées et alias sont rendues dans la sortie des modèles de blocs, pas seulement dans le contenu des pages.
- **Caches de compilation compatibles avec l’hébergement** : les caches de l’environnement d’exécution et de l’éditeur sont désormais placés par défaut hors des téléversements, acceptent des emplacements configurables et suppriment les entrées obsolètes, afin que les projets de longue durée n’accumulent pas de fichiers de cache.
- **Réconciliation incrémentale des pages** : les outils de déploiement peuvent réconcilier l’inventaire complet des pages issues de fichiers, ignorer les articles inchangés, indiquer précisément les modifications et conserver une identité de source vérifiée après l’activation.
- **Rendu à chaud plus rapide** : les caches d’exécution valides sont hydratés avant la découverte, les requêtes simultanées à froid publient un résultat atomique unique, et Tailwind conserve un cache de la taille du site avec un état de compilateur réutilisable.
- **Rendu par lots sécurisé** : les exporteurs peuvent réinitialiser l’état de rendu associé à la requête entre les documents sans reconstruire la découverte et recueillir les dépendances des sources pendant le rendu des blocs.

## Nouvelles fonctionnalités

La version 7.5 apporte de nombreuses nouvelles capacités en matière de découverte, de modèles et de stockage.

### Sources de découverte logiques

Blockstudio découvre normalement les fichiers dans les répertoires physiques des thèmes. La version 7.5 ajoute une source de plus bas niveau, API, pour les environnements d’exécution qui composent un thème à partir de superpositions, d’aperçus, de fichiers générés, de montages distants ou d’autres inventaires composites.

Une intégration peut fournir une arborescence logique finale des fichiers, tandis que Blockstudio conserve la responsabilité des blocs, des champs, des pages, des compositions, de l’éditeur de site, de Canvas, des ressources et du comportement de Tailwind :

```php title="functions.php"
use Blockstudio\Inventory_Discovery_Source;

add_filter(
    'blockstudio/discovery/sources',
    function (array $sources, string $context): array {
        if ('blocks' !== $context) {
            return $sources;
        }

        return [
            new Inventory_Discovery_Source(
                'preview:feature-card',
                '/runtime-preview/feature-card/blockstudio',
                [
                    'card/block.json' => [
                        'path' => '/theme/blockstudio/card/block.json',
                        'provenance' => ['layer' => 'parent'],
                    ],
                    'card/index.php' => [
                        'path' => '/runtime-preview/feature-card/blockstudio/card/index.php',
                        'provenance' => ['layer' => 'preview'],
                    ],
                ],
                'preview-fingerprint'
            ),
        ];
    },
    10,
    2
);
```

Les chemins logiques restent stables même lorsque les fichiers frères proviennent de différentes racines physiques. Les identifiants et empreintes des sources alimentent les identités de cache de l’environnement d’exécution et de Tailwind, les entrées surveillées invalident ces caches, et la provenance détermine où les fichiers générés peuvent être écrits. La source du système de fichiers par défaut reste inchangée pour les thèmes ordinaires.

### Modèles de l’éditeur de site issus de fichiers

Les pages et les compositions permettent déjà aux équipes de conserver les structures de contenu dans des fichiers. La version 7.5 étend ce modèle à l’éditeur de site lui-même.

```text
theme/
  templates/
    front-page/
      template.json
      index.php
  parts/
    header/
      part.json
      index.php
```

```json title="templates/front-page/template.json"
{
  "slug": "front-page",
  "title": "Front Page"
}
```

```php title="templates/front-page/index.php"
<div class="site-shell">
  <block name="core/template-part" slug="header" />

  <main>
    <h1>Welcome</h1>
    <block name="core/post-content" />
  </main>
</div>
```

Blockstudio compile la source avec le même analyseur que celui utilisé pour les pages et les compositions, puis expose le résultat à WordPress sous la forme d’un modèle ou d’une partie de modèle ordinaire de l’éditeur de site. Le modèle est visible dans l’éditeur de site, le frontend peut l’afficher, et WordPress reste responsable des personnalisations.

Ce dernier point est important. Les modèles issus de fichiers servent de source de repli. Si un utilisateur enregistre un modèle dans l’éditeur de site, WordPress crée la personnalisation habituelle dans la base de données, sous la forme de `wp_template` ou `wp_template_part`, et cette version prévaut. Réinitialisez la personnalisation pour retrouver la dernière version du fichier source.

### Déploiement incrémental des pages

Les pages issues de fichiers disposent depuis la version 7.5 d’une API de réconciliation du déploiement. Depuis 7.6.2, les appels explicites à API et `wp bs pages sync` sont les seuls points d’entrée de la synchronisation ; les requêtes ordinaires n’appliquent jamais les modifications des sources :

```php
$report = Blockstudio\Pages::reconcile([
  'authoritative' => true,
  'plan_valid' => true,
  'source' => [
    'commit' => $commit,
    'dirtyHash' => $dirtyHash,
  ],
]);
```

Le processus découvre l’inventaire complet des pages souhaité, compare le contenu et les empreintes du moteur de synchronisation, puis indique les pages créées, mises à jour, inchangées, supprimées ou en échec. Les pages dont les empreintes sont identiques ne provoquent aucune écriture dans les articles ou leurs métadonnées. Les pages gérées manquantes ne sont supprimées qu’une fois la découverte terminée sans erreur.

La réconciliation renvoie une identité de source déterministe, mais ne marque pas le déploiement comme réussi. Les outils de déploiement ne stockent cette identité qu’une fois les fichiers et routes correspondants activés et vérifiés. L’initialisation ordinaire de WP-CLI enregistre les types d’articles de collection et les règles de réécriture mis en cache sans découvrir et synchroniser chaque page.

### Îlots de blocs

La plupart des blocs Blockstudio sont rendus côté serveur. Cela convient bien à WordPress, mais crée un problème de cache bien connu : un bloc personnalisé peut compliquer la mise en cache de toute la page.

Les îlots de blocs déplacent cette frontière au niveau des blocs.

```json title="block.json"
{
  "name": "acme/cart-count",
  "blockstudio": {
    "island": "dynamic"
  }
}
```

Dans la première réponse, un îlot dynamique n’affiche qu’un espace réservé compatible avec le cache. Le navigateur envoie ensuite une seule requête groupée pour tous les îlots dynamiques prêts sur la page, et Blockstudio affiche ces fragments dans le contexte réel de la requête du visiteur.

Ainsi, un cache de page complète peut stocker la structure de la page, tandis que le nombre d’articles du panier, les commandes du compte, les blocs UI soumis à des autorisations et les autres éléments propres à chaque utilisateur restent à jour.

```php title="placeholder.php"
<div class="cart-count-placeholder">Loading cart...</div>
```

```php title="index.php"
<div class="cart-count">
  <?php echo esc_html(acme_cart_count()); ?>
</div>
```

Pour les blocs qui affichent déjà HTML compatible avec le cache et qui ont seulement besoin d’un signal de montage frontend, utilisez un îlot hydraté :

```json title="block.json"
{
  "name": "acme/tabs",
  "blockstudio": {
    "island": "hydrate"
  }
}
```

Les îlots hydratés n’effectuent pas de requête REST. Ils sont rendus normalement et reçoivent un événement `blockstudio:island:hydrate` côté frontend.

Les îlots dynamiques fonctionnent également avec les chemins de rendu programmatiques :

```php
bs_render_block([
  'name' => 'acme/cart-count',
  'data' => ['productId' => 42],
]);
```

Et avec les balises de blocs :

```html
<bs:acme-cart-count product-id="42" />
```

Le point de terminaison a volontairement une portée limitée. Il ne rend que les blocs Blockstudio enregistrés qui sont dynamiques et explicitement déclarés comme îlots dynamiques. Les attributs sont filtrés selon le schéma du bloc et la liste d’autorisation des îlots, et chaque marqueur porte une signature générée par le site WordPress qui traite la requête.

### Stockage de base de données Storh

La couche de base de données de Blockstudio prend déjà en charge les tables, SQLite, JSONC, les métadonnées d’articles et les types d’articles personnalisés. La version 7.5 ajoute `storage: "storh"` pour les projets qui souhaitent un stockage basé sur des fichiers, avec des écritures concurrentes plus sûres et des index dérivés du schéma, sans pour autant enregistrer les données actives à côté des fichiers source des blocs.

```php title="db.php"
return [
    'storage' => 'storh',
    'fields'  => [
        'title'  => ['type' => 'string', 'required' => true],
        'status' => ['type' => 'string'],
        'count'  => ['type' => 'integer'],
    ],
];
```

Les enregistrements Storh sont stockés dans les téléversements :

```text
wp-content/uploads/blockstudio/db/my-theme-my-block/default/
```

L’API public reste inchangé. `bs.db()`, REST et `Db::get()` renvoient toujours des valeurs entières `id`. En interne, Blockstudio associe ces identifiants aux identifiants de documents UUIDv7 de Storh ; le code client existant n’a donc pas besoin d’être modifié.

Chaque champ déclaré dans le schéma est indexé pour les filtres d’égalité ; les champs numériques et de type date disposent d’index de plage, et les indications explicites d’unicité sont transmises. Pour les projets qui ont commencé avec des fichiers d’amorçage JSONC, la nouvelle migration CLI conserve le fichier source et écrit un stockage Storh équivalent :

```bash
wp bs db migrate my-theme/app subscribers --to=storh
```

Ainsi, JSONC joue plus clairement le rôle d’un format simple d’amorçage et de configuration pouvant être versionné, tandis que Storh devient le meilleur backend de fichiers par défaut pour les données de production modifiables.

### Améliorations de l’analyseur et de bsui

La version 7.5 apporte également des améliorations à des éléments plus modestes qui se révèlent utiles lorsque les projets s’appuient davantage sur des modèles issus de fichiers et des UI groupés.

Le mappage des éléments gère désormais le cas courant des paragraphes richtext sans nécessiter de constructeur personnalisé. Si `<p>` correspond à un bloc Blockstudio enregistré qui n’est pas un bloc natif et comporte un attribut richtext `content`, le texte brut interne est copié dans cet attribut. Les balises imbriquées et les éléments enfants mappés sont toujours analysés comme des blocs internes.

`InnerBlocks` accepte les `allowedBlocks` tokenisés dans les modèles :

```php title="index.php"
<InnerBlocks allowedBlocks="<?php echo esc_attr(wp_json_encode([
  'core/paragraph',
  'category:content',
  'bsui/field',
])); ?>" />
```

Les jetons pris en charge sont `namespace/*`, `category:<slug>` et `@theme`. Ils sont développés sur le serveur avant que l’éditeur ne reçoive le modèle ; le chemin de rendu frontend reste donc inchangé.

Les intégrations programmatiques sont également plus prévisibles. `bs_render_block()` et `bs_block()` rendent désormais les blocs intégrés sous forme de HTML résolus par le frontend, même lorsqu’ils sont appelés depuis l’aperçu de l’éditeur d’un autre bloc. Les blocs imbriqués n’exposent donc plus de pseudo-composants `<RichText />` ou `<InnerBlocks />` bruts dans le balisage de l’aperçu.

Pour les UI groupés, `bsui/button` prend désormais en charge un attribut `icon` et `iconPosition`. Les styles en ligne `bsui/*` groupés sont émis dans une couche de cascade `@layer bsui`, et les variantes de boutons peuvent être étendues avec `blockstudio/ui/button/variants-style` ainsi qu’avec le filtre `blockstudio/blocks/attributes` existant.

Les balises de blocs peuvent aussi être davantage combinées. Un préfixe peut être résolu via un autre préfixe : `<theme-ui-input />` avec le préfixe de projet `theme` et le préfixe d’espace de noms `ui` est ainsi résolu en `bsui/input`. Les balises préfixées et alias enregistrées sont désormais aussi rendues dans la sortie des modèles de blocs, et pas seulement dans le contenu des pages ; un modèle peut donc les émettre directement sans appeler `bs_render_block()`.

Les constructeurs de blocs personnalisés enregistrés via `blockstudio/block_tags/builders` participent également de façon cohérente à l’analyse des balises et des éléments mappés. Les filtres de rendu explicites continuent de s’exécuter ensuite et peuvent remplacer le constructeur.

### Requêtes à chaud et exportations plus rapides

Les caches de l’environnement d’exécution et de l’éditeur sont désormais placés par défaut dans `wp-content/blockstudio/cache` plutôt que dans les téléversements. Leur emplacement peut être modifié via `cache.path` ou `blockstudio/cache/dir`, ce qui permet de conserver la mise en cache persistante sur les hébergeurs qui bloquent les charges utiles PHP dans les téléversements. Les caches d’exécution, de ressources de l’éditeur et de Tailwind suppriment aussi automatiquement les entrées obsolètes ; les projets de longue durée n’accumulent donc plus indéfiniment des fichiers de cache sur le disque.

Les requêtes frontend à chaud hydratent désormais un registre d’exécution valide avant de construire les sources de découverte. Cela évite de parcourir récursivement les sources, de construire les blocs, d’analyser les champs et de parcourir à nouveau les arborescences de clés de cache. Par défaut, les requêtes de production et de préproduction font confiance à un instantané de surveillance validé pendant 20 secondes, tandis que les environnements locaux et de développement vérifient toujours à chaque requête.

La création d’un cache froid est à exécution unique. Une requête construit et publie le contenu de manière atomique, tandis que les requêtes simultanées attendent le résultat. Par défaut, Tailwind conserve désormais jusqu’à 1,000 entrées compilées pendant 30 jours et réutilise l’état de construction à chaud du compilateur ; un ensemble de routes à l’échelle d’un site ne sature donc plus un cache minuscule.

Les exporteurs de longue durée peuvent appeler `Blockstudio\Batch_Render::reset()` entre les documents. Cela efface les compteurs, ressources, îlots, mises en page et générations de Tailwind associés à la requête, sans reconstruire la découverte. Le filtre `blockstudio/render/dependencies` expose les chemins des modèles et des ressources utilisés par chaque bloc rendu, pour permettre de créer des graphes de dépendances.

## Fiabilité et compatibilité

Plusieurs correctifs complètent cette version :

- Les définitions de champs modifiées via `blockstudio/blocks/attributes` déterminent désormais la validation des options au moment du rendu, ainsi que le schéma de l’éditeur. Les valeurs numériques et booléennes typées des options sont également résolues de façon cohérente.
- Les conteneurs de blocs de l’éditeur utilisent les mêmes classes générées que les rendus frontend, et Canvas peut copier les classes de corps frontend configurées via le nouveau filtre `blockstudio/editor/canvas/body_class`.
- Content Sync valide l’intégralité du plan source avant toute écriture destructive, limite les opérations de nettoyage au contenu configuré et signale les échecs d’écriture des fichiers sans faire avancer l’état de synchronisation de l’entité concernée.
- Les packages Composer inclus dans des thèmes actifs ou parents liés symboliquement résolvent les ressources de l’éditeur à partir du URL du thème public.
- Les pages issues de fichiers avec clé conservent les valeurs de champs Blockstudio gérées par l’éditeur, migrent l’ancienne structure de clé imbriquée lors de la synchronisation et acceptent zéro comme clé numérique valide.
- Les îlots dynamiques vérifient les signatures avant les filtres d’attributs de requête, ignorent le contexte de requête non signé, rétablissent les visiteurs connectés de même origine et évitent les collisions de cache entre utilisateurs anonymes.
- Les points de terminaison bruts des pages Markdown respectent désormais la visibilité des articles et leur protection par mot de passe.
- Les contrôles de l’éditeur gèrent plus fiablement les conditions vides, les valeurs de sélection de toutes les cases à cocher, les actualisations asynchrones des options, l’ordre de rendu dynamique et l’état RichText ou WYSIWYG des répéteurs.

## Types de champs personnalisés

En savoir plus sur les types de champs personnalisés présentés ci-dessus.

### Pourquoi des types de champs personnalisés ?

Blockstudio doit rester utile dès l’installation, mais les projets réels ont souvent besoin de contrôles propres à leur domaine : sélecteurs de jetons d’espacement, rôles de couleurs du système de design, dimensions adaptatives, sources d’icônes, sélecteurs de produits ou contrôles éditoriaux associés à une valeur structurée.

Avant la version 7.5, ces projets pouvaient soit composer plusieurs champs intégrés, soit créer une version dérivée de l’éditeur. La version 7.5 leur offre une solution intermédiaire prise en charge : Blockstudio gère le cycle de vie du champ, et le projet gère le contrôle.

```php title="functions.php"
add_action('init', function () {
    wp_register_script(
        'acme-field-dimensions',
        get_stylesheet_directory_uri() . '/fields/dimensions.js',
        ['blockstudio-blocks', 'wp-components', 'wp-element'],
        '1.0.0',
        true
    );

    bs_register_field_type('acme/dimensions', [
        'attribute'     => 'object',
        'default'       => [],
        'editor_script' => 'acme-field-dimensions',
        'storage'       => [
            'type'        => 'object',
            'rest_schema' => [
                'type'                 => 'object',
                'additionalProperties' => ['type' => 'string'],
            ],
        ],
    ]);
});
```

```js title="fields/dimensions.js"
const { createElement: el } = wp.element;
const { TextControl } = wp.components;

window.blockstudio.registerFieldType('acme/dimensions', {
  component(props) {
    const value =
      props.value &&
      typeof props.value === 'object' &&
      !Array.isArray(props.value)
        ? props.value
        : {};
    const sides = props.sides || ['top', 'right', 'bottom', 'left'];

    return el(
      'div',
      {},
      sides.map((side) =>
        el(TextControl, {
          key: side,
          label: side,
          value: value[side] || '',
          onChange(nextValue) {
            props.onChange({
              ...value,
              [side]: nextValue,
            });
          },
        }),
      ),
    );
  },
});
```

Le champ peut alors être utilisé dans `block.json` comme un champ natif :

```json title="block.json"
{
  "blockstudio": {
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "label": "Margin",
        "sides": ["top", "bottom"],
        "default": {
          "top": "md",
          "bottom": "md"
        }
      }
    ]
  }
}
```

### Valeurs de modèle habituelles

La valeur enregistrée est disponible dans PHP, Twig et Blade, comme tout autre attribut Blockstudio.

```php title="index.php"
<div class="<?php echo esc_attr('mt-' . ($a['margin']['top'] ?? '')); ?>">
  <?php echo esc_html($a['title'] ?? ''); ?>
</div>
```

Les mêmes chemins d’objet fonctionnent aussi dans les modèles d’extension :

```json title="extend.json"
{
  "blockstudio": {
    "extend": "core/group",
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "set": [
          {
            "attribute": "class",
            "value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
          }
        ]
      }
    ]
  }
}
```

## Notes de compatibilité

Les types de champs intégrés existants restent inchangés. Les groupes de champs réutilisables `custom/{name}` existants le restent également. Les noms des types de champs personnalisés doivent être en minuscules et comporter un espace de noms, par exemple `acme/dimensions` ; les espaces de noms `custom/` et `blockstudio/` restent réservés.

Si PHP enregistre un type de champ sans que son script d’éditeur enregistre le contrôle correspondant, Blockstudio conserve la valeur enregistrée et affiche un avis non modifiable dans l’éditeur. Si un type de champ n’est pas enregistré dans PHP, Blockstudio l’exclut des attributs WordPress générés.

## Mise à jour de maintenance de 7.5.1

7.5.1 supprime un avertissement de conversion d’un tableau en chaîne émis lors de la préparation des valeurs de sélection multiple pour le rendu. Les valeurs enregistrées et rendues étaient déjà correctes, mais les journaux de débogage pouvaient recevoir un avertissement à chaque rendu de champ.

La mise à jour `blockstudio/phpstan` v0.1.7 qui l’accompagne reconnaît également les champs imbriqués dans des groupes anonymes dans PHP, Twig, Blade et les formes d’attributs de modèle déduites. Les projets existants peuvent recevoir ce correctif de package avec `composer update blockstudio/phpstan`.
