Une donnée qui change plusieurs fois par jour (un cours de matière première, une jauge de disponibilité), affichée dans un bloc de paragraphe, sans jamais toucher à la base de données WordPress : c’est le cas d’usage qui a motivé la création d’une source de liaison personnalisée s’appuyant sur Cloudflare KV, ce magasin clé-valeur distribué déjà utilisé par ailleurs pour d’autres besoins d’infrastructure du projet. L’API Block Bindings, ouverte aux développeurs tiers depuis la sortie stable de WordPress 6.5 en avril 2024, rend ce genre de source personnalisée directement accessible depuis l’éditeur, sans bloc dédié à écrire pour chaque nouvelle donnée externe.
Le principe des Block Bindings consiste à lier un attribut de bloc natif (le contenu d’un paragraphe, l’URL d’une image, le texte d’un bouton) à une source de données externe à la valeur stockée par défaut dans post_content, sans jamais modifier le bloc lui-même : seule la source de la donnée change.
Enregistrer une source de liaison personnalisée
L’enregistrement se fait côté PHP avec la fonction register_block_bindings_source(), introduite précisément pour ce cas d’usage. Chaque source déclare un identifiant unique et un rappel de récupération de valeur :
add_action( 'init', function() {
register_block_bindings_source( 'acme/cloudflare-kv', [
'label' => __( 'Cloudflare KV', 'acme' ),
'get_value_callback' => 'acme_get_valeur_cloudflare_kv',
] );
} );
Le rappel de récupération, avec mise en cache
Le rappel reçoit les arguments de liaison définis dans l’attribut du bloc (ici, la clé recherchée dans le magasin KV) et retourne une chaîne de caractères, seule valeur que Gutenberg sait injecter dans un attribut de bloc natif. La requête vers l’API REST de Cloudflare KV est mise en cache brièvement pour éviter un appel à chaque affichage de page :
function acme_get_valeur_cloudflare_kv( array $source_args, $block_instance ) {
$cle = sanitize_key( $source_args['cle'] ?? '' );
if ( empty( $cle ) ) {
return '';
}
$cache_key = 'acme_kv_' . $cle;
$valeur = get_transient( $cache_key );
if ( false !== $valeur ) {
return $valeur;
}
$response = wp_remote_get(
sprintf(
'https://api.cloudflare.com/client/v4/accounts/%s/storage/kv/namespaces/%s/values/%s',
ACME_CF_ACCOUNT_ID,
ACME_CF_KV_NAMESPACE,
rawurlencode( $cle )
),
[
'headers' => [ 'Authorization' => 'Bearer ' . ACME_CF_API_TOKEN ],
'timeout' => 4,
]
);
if ( is_wp_error( $response ) || 200 !== wp_remote_retrieve_response_code( $response ) ) {
return $valeur !== false ? $valeur : '';
}
$valeur = wp_remote_retrieve_body( $response );
set_transient( $cache_key, $valeur, MINUTE_IN_SECONDS );
return $valeur;
}
Lier l’attribut depuis l’éditeur
Une fois la source enregistrée, elle apparaît dans le menu contextuel de liaison d’un bloc de paragraphe compatible (icône de maillon dans la barre d’outils du bloc), à côté des sources natives comme les champs personnalisés. La liaison est également déclarable directement dans le contenu sérialisé :
<!-- wp:paragraph {"metadata":{"bindings":{"content":{"source":"acme/cloudflare-kv","args":{"cle":"jauge-disponibilite"}}}}} -->
<p>Valeur par défaut si la source échoue</p>
<!-- /wp:paragraph -->
Le contenu du paragraphe déclaré dans post_content reste utilisé comme valeur de repli si la source échoue à retourner une valeur exploitable, ce qui évite un affichage vide en cas d’incident réseau vers Cloudflare.
Une limite volontaire : lecture seule
L’API Block Bindings, dans son état à cette date, ne permet l’édition d’un attribut lié que si la source déclare également un rappel d’écriture (update_value_callback). Cette source personnalisée n’en déclare volontairement aucun : écrire dans Cloudflare KV depuis l’éditeur WordPress n’entrait pas dans le périmètre du besoin, et aurait ouvert des questions de synchronisation bien plus complexes que la simple lecture d’une valeur existante. Dans l’éditeur, l’attribut lié apparaît donc verrouillé à la modification directe, ce qui est le comportement attendu pour une source en lecture seule.
- Toujours prévoir une valeur de repli exploitable dans le contenu sérialisé, la source externe pouvant échouer.
- Mettre en cache la lecture pour éviter de multiplier les appels à l’API Cloudflare à chaque affichage de page.
- Ne déclarer un rappel d’écriture que si le besoin le justifie réellement, au risque sinon de complexifier inutilement la source.
Une source de Block Bindings personnalisée gagne à rester la plus simple possible : dès qu’elle tente de gérer l’écriture en plus de la lecture, la complexité de synchronisation grandit plus vite que le bénéfice apporté à l’éditeur.
En résumé
Cette source personnalisée illustre bien l’intérêt de l’ouverture de l’API Block Bindings aux développeurs tiers : brancher une donnée externe directement sur un bloc natif, sans écrire de bloc dédié ni dupliquer cette donnée dans la base WordPress. Elle reste volontairement limitée à la lecture, ce qui suffit largement pour ce cas d’usage et simplifie considérablement sa maintenance.
