Treci la conținut

RPC

RPC (Remote Procedure Call) vă permite să definiți funcții PHP în bloc și să le apelați din frontend. În loc să înregistrați manual rute REST API, să creați controlere și să conectați apeluri fetch, scrieți o funcție în rpc.php și o apelați cu bs.fn(). Blockstudio gestionează rutarea endpoint-urilor, autentificarea, validarea nonce și serializarea JSON.

Modelul este inspirat de tRPC: definiți procedurile pe server, apoi le apelați din client cu un ajutor tipizat. Fără construirea URL, fără cod boilerplate fetch scris manual.

Cum funcționează

  1. Creați rpc.php în directorul blocului
  2. Returnează un array asociativ cu funcții denumite
  3. Blockstudio înregistrează un endpoint REST pentru fiecare funcție
  4. Clientul bs.fn() le apelează după nume
  5. Parametrii intră, iar JSON iese
Cod
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php             ← your server functions live here
├── script-inline.js    ← call them from here
└── style.css

Definirea funcțiilor

Fiecare cheie din array-ul returnat este numele unei funcții. Cea mai simplă formă este un callback direct:

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];
    },
];

Fiecare funcție primește un singur array $params și ar trebui să returneze un array. Valoarea returnată este trimisă clientului ca JSON.

Pentru opțiunile de control al accesului, folosiți formatul extins cu callback și chei suplimentare:

PHP
return [
    'admin_action' => [
        'callback'   => function (array $params): array {
            return ['ok' => true];
        },
        'capability' => 'manage_options',
    ],
];

Definiții native pentru PHP

Dacă preferați metadatele native PHP în locul array-urilor imbricate, rpc.php poate returna și un obiect cu metode adnotate. Array-urile funcționează în continuare exact la fel.

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];
    }
};

Note:

  • Numele metodelor sunt normalizate implicit la litere mici și format snake case, astfel că getStatus() devine get_status
  • Folosiți name: pentru a suprascrie explicit numele endpoint-ului
  • Access::Session corespunde comportamentului vechi 'public' => true
  • Access::Open corespunde comportamentului vechi 'public' => 'open'
  • Omiteți access: pentru comportamentul implicit, doar cu autentificare

Apelarea din JavaScript

Blockstudio injectează automat un ajutor bs.fn() în paginile care au blocuri cu funcții RPC.

Semnătură: bs.fn(functionName, params?, blockName?) -> Promise

Transmiterea numelui blocului

bs.fn() folosește ca valoare de rezervă atributul data-block al document.currentScript când omiteți al treilea argument. Blockstudio afișează atât script.js, cât și scripturile inline (script-inline.js sau script.inline.js) ca etichete <script type="module">, iar scripturile modul nu au document.currentScript, așa că în scripturile blocurilor transmiteți numele blocului ca al treilea argument:

JavaScript
const posts = await bs.fn('load_more', { offset: 10 }, 'my-theme/blog-feed');

Fără acesta, apelul generează bs.fn: block name required.

Tratarea erorilor

bs.fn() se rezolvă cu corpul JSON analizat, indiferent de starea HTTP. Când o funcție returnează un WP_Error, promisiunea se rezolvă cu un obiect care conține code, message și data, așa că verificați code:

JavaScript
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');

if (result.code) {
  console.error('RPC failed:', result.message);
}

Promisiunea este respinsă doar când cererea eșuează sau răspunsul nu este JSON.

Cu API Interactivity

RPC se combină în mod natural cu WordPress Interactivity API. Acțiunile din magazinul vostru apelează funcții de pe server și actualizează starea reactivă cu răspunsul. UI se actualizează automat:

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>

Controlul accesului

Implicit, funcțiile necesită un utilizator autentificat (conectat). Acest lucru corespunde convențiilor WordPress, conform cărora endpoint-urile REST sunt protejate implicit.

Funcții publice

Permiteți accesul neautentificat cu protecție 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
    ],
];

Pagini cache-uite

bs.fn() obține acreditări noi de la punctul final POST /wp-json/blockstudio/v1/client/credentials de aceeași origine, necache-uit. Nonce-urile WordPress cu expirare și tokenurile CSRF Blockstudio nu sunt stocate în HTML paginii, astfel încât apelurile publice continuă să funcționeze când un cache extern servește HTML mai vechi de 24 de ore.

Reîmprospătarea este întârziată: încărcarea unei pagini fără apelarea unui API nu declanșează o solicitare de acreditări. RPC și clienții bazei de date folosesc împreună reîmprospătarea, reînnoiesc acreditările după cinci minute de utilizare și reîncearcă o singură dată în cazul unui nonce sau token CSRF expirat. Erorile de capabilitate și erorile aplicației nu sunt reîncercate. Autentificarea folosește în continuare cookie-ul de conectare WordPress al vizitatorului curent; reîmprospătarea acreditărilor nu acordă acces la funcții private. Păstrați punctul final pentru acreditări în afara oricărui cache CDN sau de proxy; răspunsurile sale sunt marcate explicit private, no-store.

Funcții deschise

Pentru webhook-uri sau callback-uri API externe care au nevoie de acces cu adevărat deschis, fără niciun token:

PHP
return [
    'webhook' => [
        'callback' => function (array $params): array {
            // Called by an external service
            return ['received' => true];
        },
        'public' => 'open',  // no CSRF, no auth
    ],
];

Capabilități

Restricționați accesul la anumite capabilități WordPress. Folosiți un șir pentru o singură capabilitate sau un array dacă utilizatorul poate avea nevoie de oricare dintre ele:

PHP
return [
    'save_draft' => [
        'callback'   => function (array $params): array { /* ... */ },
        'capability' => 'edit_posts',
    ],
    'moderate' => [
        'callback'   => function (array $params): array { /* ... */ },
        'capability' => ['edit_others_posts', 'manage_options'],
    ],
];

Metode HTTP

Implicit, funcțiile acceptă doar cereri POST. Acesta este cel mai sigur comportament implicit pentru operațiunile care modifică starea. Permiteți și alte metode când este necesar:

PHP
return [
    'get_status' => [
        'callback' => function (array $params): array {
            return ['status' => 'ok'];
        },
        'methods' => ['GET', 'POST'],
    ],
];

Apeluri între blocuri

Din JavaScript

Orice bloc poate apela funcții din oricare alt bloc, transmițând numele blocului ca al treilea argument. Astfel se pot compune blocuri:

JavaScript
// Block A calling a function defined in Block B
const result = await bs.fn('load_more', { offset: 0 }, 'my-theme/blog-feed');

Din PHP

Folosiți Rpc::call() pentru apeluri între blocuri pe server. Acest lucru este util când o funcție RPC trebuie să coordoneze apeluri către alte blocuri:

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];
    },
];

Endpoint-ul REST

În culise, fiecare funcție este asociată unei rute REST:

Cod
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}

Corpul cererii: { "params": { ... } }

Răspuns: Valoarea returnată de funcția PHP, ca JSON.

Puteți apela direct aceste endpoint-uri din orice client HTTP, dar bs.fn() este metoda recomandată, deoarece gestionează automat autentificarea cu nonce.

Hook-uri

Acțiunile sunt declanșate înainte și după fiecare apel RPC, atât din REST, cât și din PHP. Toate hook-urile primesc un singur array $params:

Hook Parametri
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.
});

Filtrare

Modificați sau adăugați funcții programatic din afara blocului:

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;
});

Când să folosiți RPC în loc de Database

db.php generează automat endpoint-uri CRUD pe baza unei scheme. Folosiți-l când aveți nevoie de operațiuni standard de creare/citire/actualizare/ștergere, cu validare.

rpc.php este destinat logicii personalizate: trimiterea de e-mailuri, apelarea API-urilor externe, agregarea datelor între scheme, rularea de interogări complexe sau orice altceva care nu se încadrează în modelul CRUD.

Cele două sisteme sunt independente și complementare. Multe blocuri le folosesc pe amândouă: db.php pentru modelul de date și rpc.php pentru logica de business construită pe baza acestuia.