Aller au contenu

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

  1. Vous créez rpc.php dans le répertoire de votre bloc
  2. Il renvoie un tableau associatif de fonctions nommées
  3. Blockstudio enregistre un point de terminaison REST pour chaque fonction
  4. Le client bs.fn() les appelle par nom
  5. Les paramètres sont transmis et JSON est renvoyé
Code
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 :

PHP
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 :

PHP
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
<?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() devient get_status
  • Utilisez name: pour définir explicitement le nom du point de terminaison
  • Access::Session reproduit l’ancien comportement 'public' => true
  • Access::Open reproduit 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 :

JavaScript
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 :

JavaScript
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 :

JavaScript
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;
    },
  },
});
PHP
<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 :

PHP
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 :

PHP
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 :

PHP
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 :

PHP
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 :

JavaScript
// 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 :

PHP
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 :

Code
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
PHP
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 :

PHP
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.