Hooks PHP
Vous trouverez ci-dessous la liste de tous les hooks PHP disponibles, qui permettent d’étendre ou d’adapter les fonctionnalités de l’extension.
Chemin
Ce filtre vous permet de modifier le chemin du dossier du bloc. Par défaut, il s’agit de blockstudio dans le thème actuellement actif. Vous pouvez également créer une nouvelle instance pour plusieurs répertoires source.
add_filter('blockstudio/path', function() {
$path = get_stylesheet_directory() . '/blocks';
return $path;
});
Initialisation
global
Cette action se déclenche après l’enregistrement de tous les blocs par l’extension.
add_action('blockstudio/init', function($blocks) {
// All blocks have been registered
});
instance
Cette action se déclenche après l’enregistrement par l’extension de tous les blocs d’une instance donnée.
Le segment $instance correspond au chemin de l’instance relatif à wp-content.
$instance = 'themes/my-theme/client-blocks';
add_action("blockstudio/init/$instance", function() {
// All blocks of this instance have been registered
});
global/before
Cette action se déclenche avant l’enregistrement de tous les blocs par l’extension.
add_action('blockstudio/init/before', function() {
// Before blocks are registered
});
global/before/$instance
Cette action se déclenche avant l’enregistrement par l’extension de tous les blocs d’une instance donnée.
$instance = 'themes/my-theme/client-blocks';
add_action("blockstudio/init/before/$instance", function() {
// Before blocks of this instance are registered
});
Blocs
render
Ce filtre vous permet de modifier la sortie d’un bloc avant son rendu.
add_filter('blockstudio/blocks/render', function($content, $block, $attributes) {
// Modify the block content
return $content;
}, 10, 3);
meta
Ce filtre vous permet de modifier les données du fichier block.json avant son enregistrement.
add_filter('blockstudio/blocks/meta', function($meta, $block) {
if (str_starts_with($block['name'], 'marketing')) {
$meta['icon'] = 'megaphone';
}
return $meta;
}, 10, 2);
Le code ci-dessus modifierait l’icône de tous les blocs dont le nom commence par marketing.
conditions
Ce filtre vous permet d’ajouter des conditions personnalisées utilisables dans les blocs. Chaque type de condition correspond à une valeur que l’éditeur compare au value de la condition. Voir Conditions personnalisées.
add_filter('blockstudio/blocks/conditions', function($conditions) {
$conditions['myCustomCondition'] = 'expected';
return $conditions;
});
attributes
Ce filtre modifie une définition de champ avant l’enregistrement du bloc. La définition filtrée détermine le contrôle de l’éditeur et la validation de la valeur au moment du rendu. Consultez Filtrage pour plus d’informations.
add_filter('blockstudio/blocks/attributes', function($attribute, $block) {
// Modify this field definition before registration.
return $attribute;
}, 10, 2);
attributes/render
Ce filtre ajuste la valeur d’un champ avant son passage au modèle du bloc. Il s’exécute une fois par champ et reçoit trois arguments : $value (la valeur résolue), $key (la clé du champ, telle qu’elle est utilisée dans $a) et $block (le tableau de données du bloc que les modèles reçoivent sous la forme de $block ou $b). Enregistrez-le avec trois arguments acceptés. Consultez Filtrage pour en savoir plus.
add_filter('blockstudio/blocks/attributes/render', function($value, $key, $block) {
// Modify the value of one field before rendering.
return $value;
}, 10, 3);
attributes/files/sizes
Un champ files renvoie chaque image avec un tableau sizes contenant le URL, la largeur et la hauteur de full ainsi que de chaque taille d’image enregistrée, par exemple $image['sizes']['thumbnail'] et $image['sizes']['thumbnail-width']. Chaque taille correspond à un appel wp_get_attachment_image_src() par image, ses filtres restent donc appliqués. Les modèles qui ne lisent jamais sizes peuvent supprimer ou raccourcir la liste.
add_filter('blockstudio/blocks/attributes/files/sizes', function($sizes, $id, $size) {
// Keep only two sizes. Return an empty array to skip them, `sizes` is then null.
return ['full', 'large'];
}, 10, 3);
$sizes est la liste des noms de taille, avec full en premier (vide si aucune taille intermédiaire n’est enregistrée). $id est l’ID de la pièce jointe et $size la taille demandée pour la valeur url. Le filtre modifie le tableau sizes de chaque valeur de type fichiers dans la requête. Sans ce filtre, le tableau reste inchangé.
Renvoyez les noms de taille sous forme de chaînes. Les entrées non valides sont ignorées, les noms en double ne sont traités qu’une fois et une valeur de retour qui n’est pas un tableau ignore les tailles. url et les autres propriétés de la pièce jointe demandée restent inchangés. Ce hook ne s’exécute pas pour un champ de fichiers avec returnFormat: "url", qui ne construit pas de map de tailles.
attributes/validate
Ajustez les résultats des appels explicites bs_validate_block(), par exemple lorsqu’un filtre de rendu personnalisé résout des références enregistrées. Cela n’active pas la validation automatique lors des enregistrements ou des rendus.
add_filter('blockstudio/blocks/attributes/validate', function($findings, $name, $attrs) {
return $findings;
}, 10, 3);
Renvoyez une liste de résultats. Le filtre n’est pas appelé lorsque le bloc ne comporte aucun champ Blockstudio ni extension correspondante (null).
attributes/schema
Ajustez le schéma JSON renvoyé par bs_block_schema(), par exemple lorsqu’un filtre de rendu personnalisé résout des références enregistrées.
add_filter('blockstudio/blocks/attributes/schema', function($schema, $name) {
return $schema;
}, 10, 2);
Renvoie le tableau du schéma. Le filtre n’est pas appelé si le bloc ne contient aucun champ Blockstudio ni aucune extension correspondante (null).
attributes/populate
Ce filtre vous permet d’ajouter des données personnalisées aux options d’un champ checkbox, select ou radio. Consultez Remplir les options pour plus d’informations.
Le filtre reçoit un argument : un tableau de tous les jeux de données personnalisés, indexés par le nom utilisé dans "populate": {"type": "custom", "custom": "myCustomOptions"}.
add_filter('blockstudio/blocks/attributes/populate', function($options) {
$options['myCustomOptions'] = [
['value' => '1', 'label' => 'Option 1'],
['value' => '2', 'label' => 'Option 2'],
];
return $options;
});
components/use_block_props/render
Ce filtre vous permet de modifier la sortie du contenu useBlockProps.
Tous les filtres de composant (use_block_props, inner_blocks et rich_text) reçoivent le bloc en dernier argument. $block est le WP_Block_Type enregistré pour le bloc en cours de rendu ; $block->name correspond donc au nom du bloc, par exemple acme/hero.
$props est une chaîne d’attributs HTML, et non un tableau. Sur le site, il s’agit du résultat de
get_block_wrapper_attributes(),
par exemple class="wp-block-acme-hero my-class". Dans l’éditeur, il s’agit de l’attribut class de l’élément. Renvoyez une chaîne. Dans l’éditeur, seul l’attribut class de la chaîne renvoyée est appliqué.
add_filter('blockstudio/blocks/components/use_block_props/render', function($props, $block) {
if ($block->name !== 'acme/hero') {
return $props;
}
return str_replace('class="', 'class="my-custom-class ', $props);
}, 10, 2);
components/inner_blocks/render
Ce filtre vous permet de modifier la sortie du contenu <InnerBlocks />.
add_filter('blockstudio/blocks/components/inner_blocks/render', function($content, $block) {
return '<div class="inner-wrapper">' . $content . '</div>';
}, 10, 2);
components/inner_blocks/frontend/wrap
Ce filtre vous permet de supprimer le conteneur <InnerBlocks /> du frontend.
add_filter('blockstudio/blocks/components/inner_blocks/frontend/wrap', function($wrap, $block) {
return false; // Remove wrapper
}, 10, 2);
components/rich_text/render
Ce filtre vous permet d’ajuster la sortie du contenu <RichText />. Il reçoit la valeur de l’attribut et le bloc.
add_filter('blockstudio/blocks/components/rich_text/render', function($content, $block) {
return wp_kses_post($content);
}, 10, 2);
Balises de bloc
blockstudio/block_tags/builders
Ce filtre enregistre les constructeurs de tableaux de blocs utilisés par les balises de bloc et par les blocs personnalisés sélectionnés via blockstudio/parser/element_mapping. Chaque constructeur reçoit les attributs analysés et le contenu interne brut.
add_filter('blockstudio/block_tags/builders', function($builders, $parser) {
$builders['theme/paragraph'] = function(array $attributes, string $inner) {
$attributes['content'] = trim($inner);
return [
'blockName' => 'theme/paragraph',
'attrs' => [
'blockstudio' => [
'attributes' => $attributes,
],
],
'innerBlocks' => [],
'innerHTML' => '',
'innerContent' => [],
];
};
return $builders;
}, 10, 2);
Les filtres compatibles blockstudio/block_tags/renderers et blockstudio/parser/renderers s’exécutent après ce hook et peuvent remplacer le même nom de bloc.
blockstudio/block_tags/tag_aliases
Ce filtre permet d’enregistrer des balises de création personnalisées avec tirets, qui sont résolues en noms de blocs réels avant le recours à HTML brut. Il est utile lorsqu’un thème souhaite proposer un ensemble de balises concis et propre au projet, tout en continuant à afficher des blocs Blockstudio standard ou des blocs du cœur.
add_filter('blockstudio/block_tags/tag_aliases', function($aliases) {
$aliases['theme-button'] = 'bsui/button';
$aliases['theme-card'] = 'theme/card';
return $aliases;
});
<theme-button href="/download" label="Download" />
<theme-card title="Fast authoring">
<p>Children are parsed as nested blocks.</p>
</theme-card>
blockstudio/block_tags/prefixes
Ce filtre permet de faire correspondre des préfixes abrégés à un ou plusieurs espaces de noms de blocs. Chaque clé est un préfixe en minuscules, sans tirets. Chaque valeur peut être une chaîne d’espace de noms ou une liste ordonnée d’espaces de noms.
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
$prefixes['theme'] = ['theme-components', 'bsui'];
return $prefixes;
});
<theme-card title="Homepage" />
<theme-button label="Get started" />
<theme-ui-feature-matrix />
<theme-card> est résolu en theme-components/card. <theme-button> essaie d’abord theme-components/button, puis se rabat sur bsui/button. Les entrées blockstudio/block_tags/tag_aliases explicites sont prioritaires pour la même balise, et les balises préfixées non résolues restent inchangées.
Les préfixes peuvent être combinés : si une balise préfixée n’est pas résolue directement et que son slug est lui-même une balise préfixée enregistrée, la résolution se poursuit récursivement. Avec theme => ['theme-components'] et ui => ['bsui'], <theme-ui-input> passe au préfixe ui et est résolu en bsui/input. Les balises de préfixe et d’alias enregistrées sont également affichées dans les modèles de blocs, et pas seulement dans le contenu des pages.
Paramètres
chemin
Ce filtre permet d’ajuster le chemin du fichier blockstudio.json. Par défaut, il se trouve dans blockstudio.json, au sein du thème actuellement actif.
add_filter('blockstudio/settings/path', function() {
return get_stylesheet_directory() . '/config/blockstudio.json';
});
users/ids
Ce filtre permet d’activer l’éditeur pour des identifiants utilisateur spécifiques.
add_filter('blockstudio/settings/users/ids', function() {
return [1];
});
users/roles
Ce filtre permet d’activer l’éditeur pour des rôles utilisateur spécifiques.
add_filter('blockstudio/settings/users/roles', function() {
return ['administrator', 'editor'];
});
assets/enqueue
Ce filtre permet d’activer ou de désactiver le chargement des ressources sur l’interface publique et dans l’éditeur.
add_filter('blockstudio/settings/assets/enqueue', function() {
return false;
});
assets/reset/enabled
Ce filtre permet d’activer ou de désactiver la suppression des styles des blocs du cœur WordPress et la réinitialisation de la mise en page des utilitaires de l’éditeur.
add_filter('blockstudio/settings/assets/reset/enabled', function() {
return true;
});
assets/reset/full_width
Ce filtre permet de contrôler les types de contenu qui utilisent l’édition en pleine largeur.
add_filter('blockstudio/settings/assets/reset/full_width', function() {
return ['page'];
});
assets/minify/css
Ce filtre permet d’activer ou de désactiver la minification de CSS.
add_filter('blockstudio/settings/assets/minify/css', function() {
return true;
});
assets/minify/js
Ce filtre permet d’activer ou de désactiver la minification de JS.
add_filter('blockstudio/settings/assets/minify/js', function() {
return true;
});
assets/process/scss
Ce filtre permet d’activer ou de désactiver le traitement de SCSS dans les fichiers .css.
add_filter('blockstudio/settings/assets/process/scss', function() {
return true;
});
assets/process/scss_files
Ce filtre permet d’activer ou de désactiver la compilation des fichiers .scss en CSS.
add_filter('blockstudio/settings/assets/process/scss_files', function() {
return true;
});
assets/output
Ce filtre permet de contrôler où sont écrites les ressources compilées des blocs.
add_filter('blockstudio/settings/assets/output', function() {
return 'cache';
});
assets/inline_limit
Ce filtre vous permet de contrôler le nombre d’octets des données CSS d’un bloc externe intégrés par page.
add_filter('blockstudio/settings/assets/inline_limit', function() {
return 40000;
});
cache/enabled
Ce filtre permet d’activer ou de désactiver tous les caches de ressources d’exécution et d’éditeur adossés à des fichiers Blockstudio.
add_filter('blockstudio/settings/cache/enabled', function() {
return false;
});
cache/path
Ce filtre permet de modifier le répertoire de cache adossé au fichier Blockstudio.
add_filter('blockstudio/settings/cache/path', function() {
return 'cache/blockstudio';
});
cache/namespace_grace
Ce filtre permet de modifier la durée de conservation d’un espace de noms de cache retiré avant son nettoyage.
add_filter('blockstudio/settings/cache/namespace_grace', function() {
return 777600;
});
githooks/commit
Ce filtre indique si le hook de validation PHPStan géré par Blockstudio est activé.
add_filter('blockstudio/settings/githooks/commit', function() {
return true;
});
content/enabled
Ce filtre permet d’activer ou de désactiver la synchronisation du contenu.
add_filter('blockstudio/settings/content/enabled', function() {
return true;
});
content/id
Ce filtre permet de définir l’espace de noms propriétaire de la synchronisation du contenu.
add_filter('blockstudio/settings/content/id', function() {
return 'docs';
});
content/path
Ce filtre permet de définir le répertoire des fichiers de synchronisation du contenu.
add_filter('blockstudio/settings/content/path', function() {
return 'content';
});
content/include_page_sync_managed
Ce filtre permet d’inclure ou d’exclure les publications gérées par la synchronisation des pages.
add_filter('blockstudio/settings/content/include_page_sync_managed', function() {
return false;
});
content/authors
Ce filtre permet de configurer la gestion des auteurs par la synchronisation du contenu.
add_filter('blockstudio/settings/content/authors', function() {
return 'ignore';
});
content/post_types
Ce filtre permet de configurer les listes d’autorisation des types de contenu pour la synchronisation du contenu.
add_filter('blockstudio/settings/content/post_types', function() {
return ['team_member'];
});
content/taxonomies
Ce filtre permet de configurer les listes d’autorisation des taxonomies pour la synchronisation du contenu.
add_filter('blockstudio/settings/content/taxonomies', function() {
return ['category', 'post_tag'];
});
content/media
Ce filtre permet de configurer la gestion des médias par la synchronisation du contenu.
add_filter('blockstudio/settings/content/media', function() {
return 'manifest';
});
tailwind/enabled
Ce filtre permet d’activer ou de désactiver Tailwind.
add_filter('blockstudio/settings/tailwind/enabled', function() {
return true;
});
tailwind/config
Ce filtre permet d’ajouter une configuration Tailwind CSS personnalisée.
add_filter('blockstudio/settings/tailwind/config', function() {
return '@theme { --color-primary: pink; }';
});
tailwind/output
Ce filtre permet de choisir entre une sortie Tailwind CSS intégrée au document ou liée séparément.
add_filter('blockstudio/settings/tailwind/output', function() {
return 'link';
});
ui/enabled
Ce filtre permet d’activer ou de désactiver les composants UI inclus.
add_filter('blockstudio/settings/ui/enabled', function() {
return true;
});
editor/format_on_save
Ce filtre permet d’activer ou de désactiver le formatage du code lors de l’enregistrement.
add_filter('blockstudio/settings/editor/format_on_save', function() {
return true;
});
editor/assets
Ce filtre permet de charger des ressources supplémentaires dans l’éditeur.
add_filter('blockstudio/settings/editor/assets', function() {
return ['my-stylesheet', 'another-stylesheet'];
});
editor/markup
Ce filtre permet d’ajouter du balisage supplémentaire à la fin de l’éditeur.
add_filter('blockstudio/settings/editor/markup', function() {
return '<style>body { background: black; }</style>';
});
block_editor/disable_loading
Ce filtre permet de désactiver le chargement des blocs dans l’éditeur de blocs.
add_filter('blockstudio/settings/block_editor/disable_loading', function() {
return true;
});
block_editor/enhance
Ce filtre permet d’activer les fonctionnalités de l’éditeur Blockstudio, comme des styles de focus plus épurés et des contours au survol ou à la sélection.
add_filter('blockstudio/settings/block_editor/enhance', function() {
return true;
});
block_editor/css_classes
Ce filtre permet d’ajouter des feuilles de style dont les classes peuvent être sélectionnées dans le champ de classe.
add_filter('blockstudio/settings/block_editor/css_classes', function() {
return ['my-stylesheet', 'another-stylesheet'];
});
block_editor/css_variables
Ce filtre permet d’ajouter des feuilles de style dont les variables CSS peuvent être proposées en autocomplétion dans le champ de code.
add_filter('blockstudio/settings/block_editor/css_variables', function() {
return ['my-stylesheet', 'another-stylesheet'];
});
block_editor/blocks/allow
Ce filtre permet de contrôler les noms de blocs autorisés dans l’outil d’insertion.
add_filter('blockstudio/settings/block_editor/blocks/allow', function() {
return ['core/*', 'acf/*', 'my-theme/*'];
});
block_editor/blocks/deny
Ce filtre permet de supprimer des noms de blocs de l’outil d’insertion.
add_filter('blockstudio/settings/block_editor/blocks/deny', function() {
return ['core/embed', 'core/freeform'];
});
block_editor/blocks/directory
Ce filtre permet d’activer ou de désactiver les ressources de l’annuaire de blocs WordPress dans l’éditeur.
add_filter('blockstudio/settings/block_editor/blocks/directory', function() {
return false;
});
block_editor/blocks/categories/allow
Ce filtre permet de contrôler les slugs de catégories de blocs qui restent disponibles.
add_filter('blockstudio/settings/block_editor/blocks/categories/allow', function() {
return ['text', 'media', 'design'];
});
block_editor/blocks/categories/deny
Ce filtre permet de supprimer des slugs de catégories de blocs de l’outil d’insertion.
add_filter('blockstudio/settings/block_editor/blocks/categories/deny', function() {
return ['embed'];
});
block_editor/blocks/categories/rename
Ce filtre permet de renommer les libellés de catégories de blocs par slug.
add_filter('blockstudio/settings/block_editor/blocks/categories/rename', function() {
return [
'text' => 'Writing',
'design' => 'Layout'
];
});
block_editor/blocks/categories/order
Ce filtre permet de trier les slugs de catégories de blocs dans l’outil d’insertion.
add_filter('blockstudio/settings/block_editor/blocks/categories/order', function() {
return ['my-theme', 'text', 'media'];
});
block_editor/blocks/styles/deny
Ce filtre permet de désinscrire les styles de blocs enregistrés par PHP, selon le nom du bloc.
add_filter('blockstudio/settings/block_editor/blocks/styles/deny', function() {
return [
'my-theme/card' => ['outline'],
'my-theme/media' => ['framed']
];
});
block_editor/blocks/legacy_widgets/hide
Ce filtre permet de masquer des widgets hérités supplémentaires dans le bloc de widget hérité.
add_filter('blockstudio/settings/block_editor/blocks/legacy_widgets/hide', function() {
return ['archives', 'calendar'];
});
block_editor/patterns/core
Ce filtre permet d’activer ou de désactiver les compositions de blocs du cœur WordPress.
add_filter('blockstudio/settings/block_editor/patterns/core', function() {
return false;
});
block_editor/patterns/remote
Ce filtre permet d’activer ou de désactiver les compositions distantes de l’annuaire de compositions WordPress.
add_filter('blockstudio/settings/block_editor/patterns/remote', function() {
return false;
});
block_editor/patterns/theme
Ce filtre permet d’activer ou de désactiver les compositions de blocs fournies par le thème.
add_filter('blockstudio/settings/block_editor/patterns/theme', function() {
return false;
});
block_editor/patterns/blockstudio
Ce filtre permet d’activer ou de désactiver les compositions basées sur des fichiers Blockstudio.
add_filter('blockstudio/settings/block_editor/patterns/blockstudio', function() {
return false;
});
block_editor/patterns/categories/allow
Ce filtre permet de contrôler les slugs de catégories de compositions qui restent disponibles.
add_filter('blockstudio/settings/block_editor/patterns/categories/allow', function() {
return ['featured', 'buttons', 'columns'];
});
block_editor/patterns/categories/deny
Ce filtre permet de supprimer des slugs de catégories de compositions de l’outil d’insertion de compositions.
add_filter('blockstudio/settings/block_editor/patterns/categories/deny', function() {
return ['gallery'];
});
block_editor/patterns/categories/rename
Ce filtre permet de renommer les libellés de catégories de compositions par slug.
add_filter('blockstudio/settings/block_editor/patterns/categories/rename', function() {
return [
'featured' => 'Featured Layouts'
];
});
block_editor/patterns/categories/order
Ce filtre permet de trier les slugs de catégories de compositions dans l’outil d’insertion.
add_filter('blockstudio/settings/block_editor/patterns/categories/order', function() {
return ['featured', 'buttons'];
});
block_editor/media/openverse
Ce filtre permet d’activer ou de désactiver la catégorie de médias Openverse dans l’outil d’insertion de médias de l’éditeur de blocs.
add_filter('blockstudio/settings/block_editor/media/openverse', function() {
return false;
});
block_editor/media/image_sizes/allow
Ce filtre permet de contrôler les noms de tailles d’image qui restent disponibles dans les commandes de médias de l’éditeur.
add_filter('blockstudio/settings/block_editor/media/image_sizes/allow', function() {
return ['thumbnail', 'large'];
});
block_editor/media/image_sizes/deny
Ce filtre permet de supprimer des noms de tailles d’image des commandes de médias de l’éditeur.
add_filter('blockstudio/settings/block_editor/media/image_sizes/deny', function() {
return ['medium_large'];
});
ai/enable_context_generation
Ce filtre permet d’activer ou de désactiver la génération d’un fichier de contexte pour l’intégration d’outils LLM. Lorsqu’elle est activée, la génération rassemble dans un même document les données de blocs à jour, les paramètres Blockstudio de l’installation actuelle, tous les schémas pertinents et la documentation Blockstudio, pour les outils de développement assistés par IA.
add_filter('blockstudio/settings/ai/enable_context_generation', function() {
return true;
});
block_tags/enabled
Ce filtre permet d’activer ou de désactiver le rendu des balises de bloc au niveau de la page.
add_filter('blockstudio/settings/block_tags/enabled', function() {
return true;
});
block_tags/prefixes
Ce filtre permet d’enregistrer des préfixes abrégés correspondant à des espaces de noms pour les balises de bloc.
add_filter('blockstudio/settings/block_tags/prefixes', function() {
return [
'theme' => ['theme-components', 'bsui']
];
});
dev/grab/enabled
Ce filtre permet d’activer ou de désactiver la saisie d’éléments.
add_filter('blockstudio/settings/dev/grab/enabled', function() {
return false;
});
dev/perf
Ce filtre permet d’activer ou de désactiver le profileur de performances.
add_filter('blockstudio/settings/dev/perf', function() {
return false;
});
dev/canvas/enabled
Ce filtre permet d’activer ou de désactiver le canevas.
add_filter('blockstudio/settings/dev/canvas/enabled', function() {
return false;
});
dev/canvas/admin_bar
Ce filtre permet d’afficher ou de masquer la barre d’administration WordPress sur le canevas.
add_filter('blockstudio/settings/dev/canvas/admin_bar', function() {
return true;
});
WPML
blockstudio/wpml/config/label
Filtre le libellé de chaque clé écrite par wp bs wpml config. Consultez Modifier les libellés pour le tableau de contexte.
add_filter('blockstudio/wpml/config/label', function($label, $context) {
return str_replace(' (optional)', '', $label);
}, 10, 2);
Canevas
blockstudio/canvas/inventory
Ce filtre ajuste l’inventaire renvoyé par Canvas pour une sélection. La fonction de rappel reçoit l’objet de transfert de données de l’inventaire, la sélection d’origine et les options avec lesquelles elle a été appelée.
add_filter('blockstudio/canvas/inventory', function(array $result, array $selection, array $options) {
return $result;
}, 10, 3);
blockstudio/canvas/documents
Ce filtre ajuste les documents rendus renvoyés par Canvas, avec les mêmes trois arguments que le filtre d’inventaire.
blockstudio/canvas/item_loaded
Cette action est déclenchée une fois par enregistrement d’inventaire lors de son chargement. Elle reçoit le type d’inventaire, l’identifiant canonique de l’enregistrement et l’enregistrement normalisé.
blockstudio/canvas/source_compiled
Cette action est déclenchée après la compilation d’un fichier source pour Canvas. Elle reçoit le chemin source sélectionné et l’enregistrement source canonique.
UI inclus
blockstudio/ui/directories
Ce filtre ajuste les répertoires parcourus pour trouver les composants UI inclus.
blockstudio/ui/inventory
Ce filtre ajuste l’inventaire public des familles UI.
blockstudio/ui/examples
Ce filtre ajuste les exemples UI. Il reçoit les exemples et l’inventaire public UI dont ils sont issus.
Topologie
blockstudio/blocks/topology_refreshed
Cette action est déclenchée après la reconstruction de la topologie des blocs.
blockstudio/pages/topology_refreshed
Cette action est déclenchée après la reconstruction de la topologie des pages.
blockstudio/pages/layout_error
Cette action est déclenchée lorsqu’une mise en page échoue à s’afficher, au lieu d’échouer silencieusement.
Environnement d’exécution
blockstudio/runtime/initialized
Cette action est déclenchée une fois que l’environnement d’exécution a résolu sa configuration.
blockstudio/runtime/changed
Cette action est déclenchée lorsque l’identité résolue de l’environnement d’exécution change, ce qui déplace les espaces de noms du cache et l’état du prérendu statique.
blockstudio/performance/default_config
Ce filtre ajuste les valeurs par défaut des performances avant l’application des valeurs blockstudio.json propres au projet.
Contenu
blockstudio/content/orphan_action
Ce filtre détermine ce que la synchronisation du contenu fait d’un enregistrement qui n’a plus de source.
Bootstrap
blockstudio/url
Ce filtre modifie le URL public utilisé pour l’éditeur et les ressources d’administration de Blockstudio. Les intégrations Composer doivent l’enregistrer avant de charger le fichier d’autochargement de Blockstudio. Le deuxième argument est le répertoire physique du package.
add_filter(
'blockstudio/url',
function(string $url, string $directory) {
return get_stylesheet_directory_uri() . '/vendor/blockstudio/blockstudio/';
},
10,
2
);
Cache d’exécution
blockstudio/cache/dir
Ce filtre reçoit le répertoire de base résolu du cache, avant l’ajout d’un espace de noms d’exécution, de ressources d’éditeur ou d’un autre cache.
add_filter('blockstudio/cache/dir', function(string $directory) {
return WP_CONTENT_DIR . '/cache/blockstudio';
});
blockstudio/cache/context
Ce filtre ajoute une variante d’exécution sérialisable aux identifiants du cache. Utilisez-le lorsque la même source de découverte peut sélectionner différents inventaires logiques.
add_filter('blockstudio/cache/context', function($context, string $scope) {
return [
'preview' => get_query_var('preview_id'),
'site' => get_current_blog_id(),
];
}, 10, 2);
blockstudio/cache/site_key
Ce filtre modifie l’identité du répertoire réseau/blog pour les hôtes qui ont leur propre limite de locataire. La valeur renvoyée est assainie avant utilisation.
add_filter(
'blockstudio/cache/site_key',
function(string $key, int $networkId, int $blogId) {
return sprintf('tenant-%d-%d', $networkId, $blogId);
},
10,
3
);
blockstudio/runtime/identity
Ce filtre ajoute des informations sur l’hôte qui affectent chaque objet dans un espace d’exécution. Les empreintes de sources propres à un élément doivent plutôt être transmises comme dépendances explicites par le API responsable.
add_filter(
'blockstudio/runtime/identity',
function(array $identity, string $scope) {
$identity['deployment'] = getenv('RELEASE_SHA') ?: 'local';
return $identity;
},
10,
2
);
blockstudio/cache/watch_debounce
Définit le nombre de secondes pendant lesquelles un instantané validé de surveillance des fichiers peut être réutilisé sans nouvelle vérification du système de fichiers. La valeur par défaut est 0 dans les environnements locaux et de développement, et 20 ailleurs.
add_filter('blockstudio/cache/watch_debounce', function() {
return 30;
});
blockstudio/cache/build_wait_budget
Définit la durée, en millisecondes, pendant laquelle une requête attend qu’un processus de compilation concurrent publie le cache d’exécution ou actualise les choix renseignés avant de se dégrader. La valeur par défaut est 5000 pour les reconstructions structurelles et 4000 pour l’actualisation des choix.
add_filter('blockstudio/cache/build_wait_budget', function() {
return 2000;
});
blockstudio/cache/populate_debounce
Définit le nombre de secondes pendant lesquelles une série d’écritures de contenu, de termes, d’utilisateurs ou de métadonnées est regroupée en une seule actualisation des choix renseignés. La première écriture après une période d’inactivité déclenche immédiatement l’actualisation ; la dernière écriture d’une série est prise en compte à la fin de la fenêtre. La valeur par défaut est 30. Renvoyez 0 pour actualiser à chaque écriture.
add_filter('blockstudio/cache/populate_debounce', function() {
return 120;
});
blockstudio/cache/populate_ignored_meta_keys
Filtre les clés méta dont les écritures ne mettent jamais à jour les choix préremplis. Par défaut, il s’agit des clés que WordPress écrit pour le suivi des modifications et des connexions : _edit_lock, actualisées par l’éditeur et Heartbeat lorsqu’un article est ouvert, _edit_last, écrite lors de l’enregistrement d’un article qui déclenche déjà une actualisation, et session_tokens, écrite à la connexion et à la déconnexion. Ajoutez les clés qui changent souvent sans jamais influer sur une requête de remplissage.
add_filter('blockstudio/cache/populate_ignored_meta_keys', function(array $keys) {
$keys[] = '_my_view_counter';
return $keys;
});
blockstudio/cache/max_files_per_scope
Définit le nombre de charges utiles publiées conservées par chaque espace de cache d’exécution.
add_filter('blockstudio/cache/max_files_per_scope', function($maximum, $scope) {
return $scope === 'runtime' ? 50 : $maximum;
}, 10, 2);
blockstudio/cache/compress
Détermine si une charge utile de cache utilise des données sérialisées compressées plutôt qu’un tableau PHP simple. Par défaut, seules les charges utiles jusqu’à 1 MiB utilisent le format simple, et uniquement si la mémoire partagée OPcache active peut mettre en cache la destination. Les autres processus, les fichiers exclus et les charges utiles plus volumineuses utilisent la compression.
add_filter('blockstudio/cache/compress', function($compress, $scope) {
return $scope === 'runtime' ? false : $compress;
}, 10, 2);
Renvoyer false contourne également la limite de taille. Cela peut être utile lorsque WP-CLI sans opcache.enable_cli préchauffe des fichiers pour des workers Web utilisant OPcache, mais chaque lecteur sans OPcache analysera le tableau généré. Conservez la compression pour les charges utiles partagées volumineuses, sauf si le coût supplémentaire en mémoire est acceptable. Consultez les formats de charge utile du cache pour connaître les protections par défaut.
blockstudio/cache/protected_paths
Le nettoyage de la rétention ne doit jamais supprimer les chemins du cache. Blockstudio l’initialise avec chaque fichier référencé par la table installée de service anticipé.
add_filter('blockstudio/cache/protected_paths', function(array $paths, string $scope, string $directory) {
if ('static-prerender' === $scope) {
$paths[] = $directory . '/pinned.html';
}
return $paths;
}, 10, 3);
blockstudio/cache/outcome
Cette action signale un espace de cache partagé et un résultat, comme hit, build, miss-stale, stale-last-good ou write-failure.
add_action('blockstudio/cache/outcome', function(string $scope, string $reason) {
my_metrics()->increment("blockstudio.cache.{$scope}.{$reason}");
}, 10, 2);
blockstudio/static_prerender/request_bypass
Ce filtre reçoit la décision finale concernant la sécurité pour les requêtes anonymes, ainsi que les entrées du serveur et des cookies. Renvoyer true contourne toujours le service et la génération statiques.
add_filter(
'blockstudio/static_prerender/request_bypass',
function(bool $bypass, array $server, array $cookies) {
return $bypass || isset($cookies['commerce_session']);
},
10,
3
);
blockstudio/static_prerender/public_urls
Ce filtre fournit ou ajuste l’inventaire public complet de URL, utilisé par le préchauffeur planifié et les outils de graphe explicites.
add_filter('blockstudio/static_prerender/public_urls', function(array $urls) {
$urls[] = home_url('/custom-route/');
return array_values(array_unique($urls));
});
La valeur renvoyée par le filtre ne constitue pas l’inventaire final. Elle est soumise à une vérification de la possibilité de mise en cache, qui élimine les éléments correspondant à un chemin dynamique configuré ainsi que ceux contournés par défaut : /wp-admin, /wp-json, /wp-login.php, /xmlrpc.php, tout chemin contenant /feed/ et les résultats de recherche sous le chemin d’accueil du site, à la base de recherche (/search/ par défaut). Une entrée URL que vous ajoutez peut donc être écartée sans avertissement. Si une route attendue manque dans l’inventaire généré, vérifiez qu’elle respecte ces règles avant de conclure que le filtre ne s’est pas exécuté.
blockstudio/static_prerender/render_internal
Ce filtre implémente le transport par lots facultatif en processus. Renvoyez un tableau de résultats normalisé ou laissez la valeur inchangée pour que le moteur de rendu utilise sa solution de repli HTTP configurée. Le résultat contient html et, éventuellement, status, dependencies, virtualHashes et headers ; les en-têtes nommés dans performance.staticPrerender.replayHeaders sont enregistrés avec le document.
add_filter(
'blockstudio/static_prerender/render_internal',
function($result, string $url, array $options) {
return my_static_renderer()->render($url, $options);
},
10,
3
);
blockstudio/static_prerender/cacheable_html
Ce filtre prend la décision finale après que Blockstudio a vérifié que la sortie est un document HTML complet sans marqueur d’absence de cache et que le statut de réponse observé indique un succès. Le troisième argument est le statut observé ou null si aucun statut n’a été déclaré.
add_filter('blockstudio/static_prerender/cacheable_html', function(bool $cacheable, string $html, ?int $status) {
return $cacheable && !str_contains($html, 'data-personalized');
}, 10, 3);
blockstudio/static_prerender/outcome
Cette action signale les résultats du prérendu statique, notamment les succès, les échecs, les écritures, les écritures de graphe, les entrées obsolètes et les erreurs.
add_action('blockstudio/static_prerender/outcome', function(string $reason) {
my_metrics()->increment("blockstudio.prerender.{$reason}");
});
blockstudio/tailwind/cache_max_files
Définit le nombre maximal d’entrées compilées Tailwind CSS. La valeur par défaut est 1000.
add_filter('blockstudio/tailwind/cache_max_files', function() {
return 1500;
});
blockstudio/tailwind/cache_max_age
Définit l’âge maximal, en secondes, des entrées compilées Tailwind CSS. La valeur par défaut est de 30 jours et le minimum est d’une heure.
add_filter('blockstudio/tailwind/cache_max_age', function() {
return 14 * DAY_IN_SECONDS;
});
Administration
activé
Ce filtre permet d’activer ou de désactiver la page d’administration Blockstudio sous Outils > Blockstudio.
add_filter('blockstudio/admin/enabled', function() {
return false;
});
Ressources
editor/canvas/body_class
Lorsque la réinitialisation des ressources est activée, ce filtre ajuste les classes de corps assainies de l’interface publique qui sont copiées dans le canevas de l’éditeur de blocs.
add_filter('blockstudio/editor/canvas/body_class', function(array $classes) {
return array_values(array_diff($classes, ['logged-in']));
});
activer
Ce filtre permet de désactiver le traitement et le chargement d’un type de ressource spécifique.
add_filter('blockstudio/assets/enable', function($enable, $type, $block) {
if ($type === 'css' && $block['name'] === 'my/block') {
return false;
}
return $enable;
}, 10, 3);
désactiver
Ce filtre permet de désactiver des ressources spécifiques par leur identifiant. Les ressources dont l’identifiant figure dans le tableau renvoyé ne seront pas affichées sur l’interface publique.
add_filter('blockstudio/assets/disable', function($disabled) {
$disabled[] = 'my-block-style';
return $disabled;
});
process/scss/import_paths
Ce filtre permet d’ajouter des chemins supplémentaires à l’instruction @import du compilateur SCSS.
add_filter('blockstudio/assets/process/scss/import_paths', function($paths) {
$paths[] = get_stylesheet_directory() . '/scss';
return $paths;
});
process/scss/prelude
Ce filtre permet d’ajouter du code partagé Sass avant la compilation de chaque fichier SCSS.
add_filter('blockstudio/assets/process/scss/prelude', function($prelude, $path, $scss) {
return '@import "functions";' . "\n"
. '@import "variables";' . "\n"
. '@import "mixins";';
}, 10, 3);
process/css/content
Ce filtre permet d’ajuster le contenu du fichier CSS avant sa compilation.
add_filter('blockstudio/assets/process/css/content', function($content, $block) {
return str_replace('old-class', 'new-class', $content);
}, 10, 2);
process/js/content
Ce filtre permet d’ajuster le contenu du fichier JS avant sa compilation.
add_filter('blockstudio/assets/process/js/content', function($content, $block) {
return $content;
}, 10, 2);
Tampon
activé
Blockstudio met en mémoire tampon la réponse de l’interface publique afin que les balises de style et de script rendues dans le corps puissent être déplacées vers l’en-tête et le pied de page, et que Tailwind puisse analyser le document entier. La mise en mémoire tampon consiste à conserver et analyser le document complet à chaque requête de l’interface publique. Un site qui ne rend aucun élément de ressource de bloc Blockstudio et n’utilise pas Tailwind peut renvoyer false pour ignorer les deux opérations.
add_filter('blockstudio/buffer/enabled', '__return_false');
La mise en tampon est également désactivée dans l’administration et dans l’aperçu du Customizer. Appelez bs_is_buffering() depuis wp_enqueue_scripts ou une étape ultérieure pour savoir si la réponse actuelle est mise en tampon. La fonction renvoie false avant que la décision soit prise à template_redirect.
sortie
Ce filtre reçoit le document HTML complet en mémoire tampon avant son envoi. Le déplacement des ressources de Blockstudio s’exécute à la priorité 1000000 et la compilation de Tailwind à la priorité 999999. Exécutez votre filtre plus tôt pour voir le document avant ces opérations, ou plus tard pour voir la sortie finale.
add_filter('blockstudio/buffer/output', function(string $html) {
return $html;
}, 2000000);
Rendu
dépendances
Ce filtre signale le modèle sélectionné et les dépendances de ressources chaque fois que Blockstudio affiche un bloc. Il est utile pour les exportateurs statiques et les autres collecteurs de dépendances exécutés dans le processus.
add_filter(
'blockstudio/render/dependencies',
function($paths, $name, $block, $isEditor, $isPreview) {
my_dependency_graph()->add($name, $paths);
return $paths;
},
10,
5
);
global
Ce filtre permet d’ajuster la sortie de la page avant son rendu.
add_filter('blockstudio/render', function($content) {
return $content;
});
en-tête
Ce filtre vous permet d’ajuster la sortie de la balise <head> avant son rendu. Il s’exécute uniquement lorsque Blockstudio met la réponse en tampon ; consultez bs_is_buffering().
add_filter('blockstudio/render/head', function($content) {
return $content . '<meta name="custom" content="value">';
});
pied de page
Ce filtre permet d’ajuster la sortie de </body> avant son rendu.
add_filter('blockstudio/render/footer', function($content) {
return $content . '<script>console.log("loaded")</script>';
});
Gestion des erreurs
error/logged
Action déclenchée après la consignation d’une erreur. Utilisez-la pour envoyer les erreurs à des services de journalisation externes.
add_action('blockstudio/error/logged', function($message, $level, $context) {
if ($level === 'error') {
my_external_logger($message, $context);
}
}, 10, 3);
error/exception
Action déclenchée après la gestion d’une exception.
add_action('blockstudio/error/exception', function($exception, $context) {
my_error_tracker($exception);
}, 10, 2);
Base de données
Tous les hooks de base de données reçoivent un seul tableau $params.
db/before_create
Action déclenchée avant la création d’un enregistrement.
add_action('blockstudio/db/before_create', function($params) {
// $params: block, schema, data, storage
});
db/after_create
Action déclenchée après la création d’un enregistrement.
add_action('blockstudio/db/after_create', function($params) {
// $params: block, schema, record, storage
wp_mail($params['record']['email'], 'Welcome!', 'Thanks for subscribing.');
});
db/before_update
Action déclenchée avant la mise à jour d’un enregistrement.
add_action('blockstudio/db/before_update', function($params) {
// $params: block, schema, id, data, storage
});
db/after_update
Action déclenchée après la mise à jour d’un enregistrement.
add_action('blockstudio/db/after_update', function($params) {
// $params: block, schema, id, record, storage
});
db/before_delete
Action déclenchée avant la suppression d’un enregistrement.
add_action('blockstudio/db/before_delete', function($params) {
// $params: block, schema, id, storage
});
db/after_delete
Action déclenchée après la suppression d’un enregistrement.
add_action('blockstudio/db/after_delete', function($params) {
// $params: block, schema, id, storage
});
RPC
Tous les hooks RPC reçoivent un seul tableau $params.
rpc/before_call
Action déclenchée avant l’appel d’une fonction RPC.
add_action('blockstudio/rpc/before_call', function($params) {
// $params: block, function, params
});
rpc/after_call
Action déclenchée après l’appel d’une fonction RPC.
add_action('blockstudio/rpc/after_call', function($params) {
// $params: block, function, params, result
});