Gå til indhold

RPC

RPC (Remote Procedure Call) lader dig definere PHP-funktioner i din blok og kalde dem fra frontend. I stedet for manuelt at registrere REST-API-ruter, oprette controllere og koble fetch-kald sammen skriver du en funktion i rpc.php og kalder den med bs.fn(). Blockstudio håndterer rutetildeling til endpoints, godkendelse, nonce-validering og JSON-serialisering.

Mønstret er inspireret af tRPC: Definér procedurer på serversiden, og kald dem fra klienten med en typet hjælper. Ingen opbygning af URL og intet manuelt fetch-standardkode.

Sådan fungerer det

  1. Du opretter rpc.php i din blokmappe
  2. Den returnerer et associativt array med navngivne funktioner
  3. Blockstudio registrerer et REST-endpoint for hver funktion
  4. bs.fn()-klienten kalder dem ved navn
  5. Parametre sendes ind, og JSON kommer ud
Kode
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php             ← your server functions live here
├── script-inline.js    ← call them from here
└── style.css

Definition af funktioner

Hver nøgle i det returnerede array er et funktionsnavn. Den enkleste form er et direkte callback:

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

Hver funktion modtager ét $params-array og bør returnere et array. Returværdien sendes til klienten som JSON.

Brug den udvidede form med callback og flere nøgler til adgangskontrol:

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

PHP-native definitioner

Hvis du foretrækker metadata, der er native i PHP, frem for indlejrede arrays, kan rpc.php også returnere et objekt med metoder forsynet med attributter. Arrays fungerer stadig præcis som før.

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

Bemærk:

  • Metodenavne normaliseres som standard til små bogstaver og snake case, så getStatus() bliver til get_status
  • Brug name: til eksplicit at tilsidesætte endpoint-navnet
  • Access::Session svarer til den gamle 'public' => true-adfærd
  • Access::Open svarer til den gamle 'public' => 'open'-adfærd
  • Udelad access: for standardadfærden, hvor kun godkendte brugere har adgang

Kald fra JavaScript

Blockstudio indsætter automatisk en bs.fn()-helper på sider med blokke, der har RPC-funktioner.

Signatur: bs.fn(functionName, params?, blockName?) -> Promise

Angivelse af bloknavnet

bs.fn() bruger værdien af attributten data-block i document.currentScript som reserve, når det tredje argument udelades. Blockstudio udskriver både script.js og inline-scripts (script-inline.js eller script.inline.js) som <script type="module">-tags, og modul-scripts har ingen document.currentScript. Angiv derfor bloknavnet som det tredje argument i blok-scripts:

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

Uden det kaster kaldet bs.fn: block name required.

Fejlhåndtering

bs.fn() løses med den fortolkede JSON-body uanset HTTP-status. Når en funktion returnerer en WP_Error, løses promise med et objekt, der indeholder dens code, message og data. Kontrollér derfor code:

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

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

Promise afvises kun, når selve anmodningen mislykkes, eller svaret ikke er JSON.

Med Interactivity-API

RPC passer naturligt sammen med WordPress Interactivity-API. Dine store-handlinger kalder serverfunktioner og opdaterer reaktiv tilstand med svaret. UI opdateres automatisk:

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>

Adgangskontrol

Som standard kræver funktioner en godkendt (indlogget) bruger. Det følger WordPress-konventionerne, hvor REST-endpoints som standard er beskyttet.

Offentlige funktioner

Tillad adgang uden godkendelse med CSRF-beskyttelse:

PHP
return [
    'get_count' => [
        'callback' => function (array $params): array {
            return ['count' => wp_count_posts()->publish];
        },
        'public' => true,    // public + CSRF protected via X-BS-Token
    ],
];

Cachelagrede sider

bs.fn() henter friske legitimationsoplysninger fra det ikke-cachelagrede POST /wp-json/blockstudio/v1/client/credentials-endpoint med samme oprindelse. WordPress-nonces og Blockstudio-CSRF-tokens, der udløber, gemmes ikke i sidens HTML, så offentlige kald fortsat fungerer, når en ekstern sidecache viser HTML, der er ældre end 24 timer.

Opdateringen sker efter behov: Indlæsning af en side uden et API-kald udløser ikke en anmodning om legitimationsoplysninger. RPC- og databaseklienter deler opdateringen, fornyer legitimationsoplysninger efter fem minutters brug og forsøger én gang til ved en udløbet nonce eller et udløbet CSRF-token. Fejl med rettigheder og programfejl forsøges ikke igen. Godkendelse følger stadig den aktuelle besøgendes login-cookie fra WordPress; opdatering af legitimationsoplysninger giver ikke adgang til private funktioner. Hold endpointet til legitimationsoplysninger uden for enhver CDN- eller proxycache; dets svar er eksplicit markeret som private, no-store.

Åbne funktioner

Til webhooks eller eksterne API-callbacks, der kræver helt åben adgang uden token:

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

Tilladelser

Begræns adgangen til bestemte WordPress-tilladelser. Brug en streng til en enkelt tilladelse eller et array, hvis brugeren skal have en hvilken som helst af dem:

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

HTTP-metoder

Som standard accepterer funktioner kun POST-anmodninger. Det er den sikreste standard for handlinger, der ændrer tilstand. Tillad flere metoder efter behov:

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

Kald på tværs af blokke

Fra JavaScript

Alle blokke kan kalde funktioner i andre blokke ved at angive bloknavnet som det tredje argument. Det gør det muligt at kombinere blokke:

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

Fra PHP

Brug Rpc::call() til kald mellem blokke på serversiden. Det er nyttigt, når en RPC-funktion skal koordinere kald til andre blokke:

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

REST-endpoint

Bag kulisserne knyttes hver funktion til en REST-rute:

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

Anmodningsbody: { "params": { ... } }

Svar: Returværdien fra funktionen PHP som JSON.

Du kan kalde disse endpoints direkte fra enhver HTTP-klient, men bs.fn() er den anbefalede metode, da den automatisk håndterer nonce-godkendelse.

Hooks

Handlinger udløses før og efter hvert RPC-kald, både fra REST og PHP. Alle hooks modtager ét $params-array:

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

Filtrering

Redigér eller tilføj funktioner programmatisk uden for blokken:

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

Hvornår skal du bruge RPC eller Database?

db.php genererer automatisk CRUD-endpoints ud fra et skema. Brug det, når du har brug for standardhandlinger til oprettelse, læsning, opdatering og sletning med validering.

rpc.php bruges til brugerdefineret logik: afsendelse af e-mails, kald til eksterne API’er, sammenlægning af data på tværs af skemaer, kørsel af komplekse forespørgsler eller alt, der ikke passer til CRUD-mønstret.

De to systemer er uafhængige og supplerer hinanden. Mange blokke bruger begge: db.php til datamodellen og rpc.php til forretningslogikken oven på den.