RPC
RPC (appel de procédure à distance) vous permet de définir des fonctions PHP dans votre bloc et de les appeler depuis le frontend. Au lieu d’enregistrer manuellement des routes REST API, de créer des contrôleurs et de configurer des appels fetch, vous écrivez une fonction dans rpc.php et l’appelez avec bs.fn(). Blockstudio gère le routage des points de terminaison, l’authentification, la validation du nonce et la sérialisation JSON.
Le modèle s’inspire de tRPC : définissez vos procédures côté serveur et appelez-les depuis le client avec un utilitaire typé. Pas de construction de URL, ni de code répétitif fetch à écrire manuellement.
Fonctionnement
- Vous créez
rpc.phpdans le répertoire de votre bloc - Il renvoie un tableau associatif de fonctions nommées
- Blockstudio enregistre un point de terminaison REST pour chaque fonction
- Le client
bs.fn()les appelle par nom - Les paramètres sont transmis et JSON est renvoyé
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php ← your server functions live here
├── script-inline.js ← call them from here
└── style.css
Définir des fonctions
Chaque clé du tableau renvoyé correspond à un nom de fonction. La forme la plus simple est une fonction de rappel directe :
return [
'subscribe' => function (array $params): array {
$email = sanitize_email($params['email']);
// process subscription
return ['success' => true];
},
'load_more' => function (array $params): array {
$offset = (int) ($params['offset'] ?? 0);
$posts = get_posts(['offset' => $offset, 'numberposts' => 5]);
return ['posts' => $posts];
},
];
Chaque fonction reçoit un seul tableau $params et doit renvoyer un tableau. La valeur renvoyée est transmise au client sous forme de JSON.
Pour définir les options de contrôle d’accès, utilisez le format développé avec callback et des clés supplémentaires :
return [
'admin_action' => [
'callback' => function (array $params): array {
return ['ok' => true];
},
'capability' => 'manage_options',
],
];
Définitions natives PHP
Si vous préférez les métadonnées natives de PHP aux tableaux imbriqués, rpc.php peut également renvoyer un objet avec des méthodes attributées. Les tableaux fonctionnent toujours exactement de la même façon.
<?php
use Blockstudio\Attributes\Rpc;
use Blockstudio\Rpc\Access;
use Blockstudio\Rpc\Method;
return new class {
#[Rpc(access: Access::Session)]
public function subscribe(array $params): array {
$email = sanitize_email($params['email'] ?? '');
return ['success' => !empty($email)];
}
#[Rpc(name: 'status', methods: [Method::Get, Method::Post])]
public function getStatus(array $params): array {
return ['status' => 'ok'];
}
#[Rpc(access: Access::Open)]
public function webhook(array $params): array {
return ['received' => true];
}
};
Remarques :
- Par défaut, les noms de méthode sont normalisés en minuscules avec des traits de soulignement. Ainsi,
getStatus()devientget_status - Utilisez
name:pour définir explicitement le nom du point de terminaison Access::Sessionreproduit l’ancien comportement'public' => trueAccess::Openreproduit l’ancien comportement'public' => 'open'- Omettez
access:pour conserver le comportement par défaut, réservé aux utilisateurs authentifiés
Appeler depuis JavaScript
Blockstudio injecte automatiquement un utilitaire bs.fn() sur les pages contenant des blocs avec des fonctions RPC.
Signature : bs.fn(functionName, params?, blockName?) -> Promise
Transmettre le nom du bloc
Si vous omettez le troisième argument, bs.fn() reprend la valeur de l’attribut data-block de document.currentScript. Blockstudio affiche à la fois script.js et les scripts intégrés (script-inline.js ou script.inline.js) sous forme de balises <script type="module"> ; les scripts de module n’ont pas de document.currentScript. Dans les scripts de bloc, transmettez donc le nom du bloc comme troisième argument :
const posts = await bs.fn('load_more', { offset: 10 }, 'my-theme/blog-feed');
Sans cet argument, l’appel déclenche bs.fn: block name required.
Gestion des erreurs
bs.fn() renvoie le corps JSON analysé, quel que soit le statut HTTP. Lorsqu’une fonction renvoie un WP_Error, la promesse renvoie un objet contenant son code, son message et son data. Vérifiez donc code :
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');
if (result.code) {
console.error('RPC failed:', result.message);
}
La promesse n’est rejetée que si la requête échoue ou si la réponse n’est pas JSON.
Avec l’API d’interactivité
RPC s’associe naturellement à l’WordPress d’interactivité API. Les actions de votre magasin appellent des fonctions serveur et mettent à jour l’état réactif avec la réponse. Le UI se met à jour automatiquement :
import { store, getContext } from '@wordpress/interactivity';
store('myTheme/newsletter', {
actions: {
subscribe: async () => {
const ctx = getContext();
ctx.loading = true;
ctx.error = '';
try {
ctx.result = await bs.fn('subscribe', { email: ctx.email }, 'my-theme/newsletter');
ctx.success = !ctx.result.code;
} catch (e) {
ctx.error = 'Something went wrong.';
}
ctx.loading = false;
},
},
});
<div
data-wp-interactive="myTheme/newsletter"
data-wp-context='{"email":"","loading":false,"success":false,"error":"","result":null}'
useBlockProps
>
<input
type="email"
data-wp-bind--value="context.email"
data-wp-on--input="actions.updateEmail"
/>
<button
data-wp-on--click="actions.subscribe"
data-wp-bind--disabled="context.loading"
>Subscribe</button>
<p data-wp-if="context.error" data-wp-text="context.error"></p>
<p data-wp-if="context.success">Thanks for subscribing!</p>
</div>
Contrôle d’accès
Par défaut, les fonctions exigent un utilisateur authentifié (connecté). Cela correspond aux conventions WordPress, selon lesquelles les points de terminaison REST sont protégés par défaut.
Fonctions publiques
Autorisez l’accès sans authentification avec une protection contre les attaques CSRF :
return [
'get_count' => [
'callback' => function (array $params): array {
return ['count' => wp_count_posts()->publish];
},
'public' => true, // public + CSRF protected via X-BS-Token
],
];
Pages mises en cache
bs.fn() récupère des identifiants à jour depuis le point de terminaison POST /wp-json/blockstudio/v1/client/credentials de même origine sans cache. Les nonces WordPress et les jetons CSRF Blockstudio à expiration ne sont pas stockés dans le HTML de la page ; les appels publics continuent donc de fonctionner lorsqu’un cache de page externe sert un HTML datant de plus de 24 heures.
L’actualisation est différée : le chargement d’une page sans appel à un API ne déclenche aucune demande d’identifiants. RPC et les clients de base de données partagent l’actualisation, renouvellent les identifiants après cinq minutes d’utilisation et réessaient une fois en cas de nonce ou de jeton CSRF expiré. Les échecs de capacité et les erreurs d’application ne donnent lieu à aucune nouvelle tentative. L’authentification utilise toujours le cookie de connexion WordPress du visiteur actuel ; l’actualisation des identifiants ne donne pas accès aux fonctions privées. Placez le point de terminaison d’identifiants hors de tout cache CDN ou de proxy ; ses réponses sont explicitement marquées private, no-store.
Fonctions ouvertes
Pour les webhooks ou les rappels API externes qui doivent être entièrement ouverts, sans jeton :
return [
'webhook' => [
'callback' => function (array $params): array {
// Called by an external service
return ['received' => true];
},
'public' => 'open', // no CSRF, no auth
],
];
Capacités
Limitez l’accès à des capacités WordPress précises. Utilisez une chaîne pour une seule capacité ou un tableau si l’utilisateur doit en avoir au moins une :
return [
'save_draft' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => 'edit_posts',
],
'moderate' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => ['edit_others_posts', 'manage_options'],
],
];
Méthodes HTTP
Par défaut, les fonctions n’acceptent que les requêtes POST. C’est le réglage le plus sûr pour les opérations qui modifient l’état. Autorisez d’autres méthodes si nécessaire :
return [
'get_status' => [
'callback' => function (array $params): array {
return ['status' => 'ok'];
},
'methods' => ['GET', 'POST'],
],
];
Appels entre blocs
Depuis JavaScript
Un bloc peut appeler les fonctions de n’importe quel autre bloc en transmettant le nom de ce bloc comme troisième argument. Cela permet de composer les blocs :
// Block A calling a function defined in Block B
const result = await bs.fn('load_more', { offset: 0 }, 'my-theme/blog-feed');
Depuis PHP
Utilisez Rpc::call() pour effectuer des appels entre blocs côté serveur. Cette méthode est utile lorsqu’une fonction RPC doit coordonner des appels vers d’autres blocs :
use Blockstudio\Rpc;
return [
'refresh_dashboard' => function (array $params): array {
$feed = Rpc::call('my-theme/blog-feed', 'load_more', ['offset' => 0]);
$stats = Rpc::call('my-theme/analytics', 'get_summary', []);
return ['feed' => $feed, 'stats' => $stats];
},
];
Point de terminaison REST
En interne, chaque fonction correspond à une route REST :
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}
Corps de la requête : { "params": { ... } }
Réponse : valeur renvoyée par la fonction PHP sous forme de JSON.
Vous pouvez appeler directement ces points de terminaison depuis n’importe quel client HTTP, mais bs.fn() est recommandé, car il gère automatiquement l’authentification par nonce.
Hooks
Les actions sont déclenchées avant et après chaque appel RPC, depuis REST comme depuis PHP. Tous les hooks reçoivent un seul tableau $params :
| Hook | Paramètres |
|---|---|
blockstudio/rpc/before_call |
block, function, params |
blockstudio/rpc/after_call |
block, function, params, result |
add_action('blockstudio/rpc/after_call', function ($params) {
// Log every RPC call
error_log($params['block'] . '::' . $params['function'] . ' called');
});
add_action('blockstudio/rpc/before_call', function ($params) {
// Rate limiting, audit logging, etc.
});
Filtrer
Modifiez ou ajoutez des fonctions par programmation depuis l’extérieur du bloc :
add_filter('blockstudio/rpc', function (array $functions): array {
$functions['my-theme/hero']['custom_action'] = [
'callback' => function (array $params): array {
return ['ok' => true];
},
'public' => false,
];
return $functions;
});
Quand utiliser RPC ou la base de données
db.php génère automatiquement des points de terminaison CRUD à partir d’un schéma. Utilisez-le pour les opérations standard de création, lecture, mise à jour et suppression avec validation.
rpc.php sert à la logique personnalisée : envoyer des e-mails, appeler des API externes, agréger des données de plusieurs schémas, exécuter des requêtes complexes ou gérer tout ce qui ne correspond pas au modèle CRUD.
Les deux systèmes sont indépendants et complémentaires. De nombreux blocs utilisent les deux : db.php pour le modèle de données et rpc.php pour la logique métier qui s’y ajoute.