Hoppa till innehåll

RPC

RPC (Remote Procedure Call) låter dig definiera PHP-funktioner i ditt block och anropa dem från frontend. I stället för att manuellt registrera REST-API-rutter, skapa styrenheter och koppla ihop fetch-anrop skriver du en funktion i rpc.php och anropar den med bs.fn(). Blockstudio hanterar routningen av slutpunkter, autentisering, nonce-validering och JSON-serialisering.

Mönstret är inspirerat av tRPC: definiera procedurerna på serversidan och anropa dem från klienten med en typad hjälpfunktion. Ingen konstruktion av URL, inget manuellt fetch-standardarbete.

Så fungerar det

  1. Du skapar rpc.php i blockkatalogen
  2. Den returnerar en associativ array med namngivna funktioner
  3. Blockstudio registrerar en REST-slutpunkt för varje funktion
  4. bs.fn()-klienten anropar dem med namn
  5. Parametrar skickas in, JSON kommer ut
Kod
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php             ← your server functions live here
├── script-inline.js    ← call them from here
└── style.css

Definiera funktioner

Varje nyckel i den returnerade arrayen är ett funktionsnamn. Den enklaste formen är en direkt återanropsfunktion:

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

Varje funktion får en enda $params-array och ska returnera en array. Returvärdet skickas till klienten som JSON.

Använd det utökade formatet med callback och ytterligare nycklar för åtkomstkontroll:

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

Definitioner för PHP

Om du föredrar PHP-inbyggd metadata framför nästlade arrayer kan rpc.php också returnera ett objekt med attributförsedda metoder. Arrayer fungerar fortfarande på samma sätt.

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

Observera:

  • Metodnamn normaliseras som standard till gemener med snake case, så getStatus() blir get_status
  • Använd name: för att uttryckligen ange slutpunktens namn
  • Access::Session motsvarar det gamla beteendet för 'public' => true
  • Access::Open motsvarar det gamla beteendet för 'public' => 'open'
  • Utelämna access: för standardbeteendet, där endast autentiserade användare tillåts

Anropa från JavaScript

Blockstudio lägger automatiskt till en hjälpfunktion för bs.fn() på sidor med block som har RPC-funktioner.

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

Ange blockets namn

bs.fn() använder attributet data-block för document.currentScript om det tredje argumentet utelämnas. Blockstudio skriver ut både script.js och inline-skript (script-inline.js eller script.inline.js) som <script type="module">-taggar, och moduls­kript saknar document.currentScript. Ange därför blockets namn som tredje argument i blockskript:

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

Utan det ger anropet felet bs.fn: block name required.

Felhantering

bs.fn() löses med den parsade svarskroppen i JSON oavsett HTTP-status. När en funktion returnerar ett WP_Error löses löftet med ett objekt som innehåller dess code, message och data. Kontrollera därför code:

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

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

Löftet avvisas bara när själva begäran misslyckas eller svaret inte är JSON.

Med Interactivity API

RPC passar naturligt ihop med WordPress Interactivity API. Åtgärder i din lagring anropar serverfunktioner och uppdaterar reaktivt tillstånd med svaret. UI uppdateras automatiskt:

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>

Åtkomstkontroll

Som standard kräver funktioner en autentiserad (inloggad) användare. Det följer WordPress-konventioner, där REST-slutpunkter skyddas som standard.

Publika funktioner

Tillåt åtkomst utan autentisering med CSRF-skydd:

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

Cachade sidor

bs.fn() hämtar nya inloggningsuppgifter från slutpunkten POST /wp-json/blockstudio/v1/client/credentials med samma ursprung, som inte cachas. Utgående WordPress-nonce och Blockstudio CSRF-token lagras inte i sidans HTML, så offentliga anrop fortsätter att fungera när en extern sidcache visar HTML som är äldre än 24 timmar.

Uppdateringen sker vid behov: om du laddar en sida utan att anropa en API görs ingen förfrågan om inloggningsuppgifter. RPC och databasklienterna delar på uppdateringen, förnyar uppgifterna efter fem minuters användning och gör ett nytt försök vid utgången nonce eller CSRF-token. Behörighetsfel och programfel leder inte till nya försök. Autentiseringen följer fortfarande den aktuella besökarens inloggningscookie för WordPress. Att uppgifterna uppdateras ger inte åtkomst till privata funktioner. Placera slutpunkten för inloggningsuppgifter utanför alla cachelagringar för CDN eller proxyservrar. Svaren är uttryckligen märkta private, no-store.

Öppna funktioner

För webhookar eller externa API-återanrop som behöver helt öppen åtkomst utan någon token:

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

Behörigheter

Begränsa till specifika WordPress-behörigheter. Använd en sträng för en enda behörighet eller en array om användaren behöver ha minst en av 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'],
    ],
];

Metoder för HTTP

Som standard accepterar funktioner bara POST-begäranden. Det är det säkraste standardvalet för åtgärder som ändrar tillstånd. Tillåt ytterligare metoder vid behov:

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

Anrop mellan block

Från JavaScript

Alla block kan anropa funktioner i andra block genom att ange blockets namn som ett tredje argument. Det gör att block kan samverka:

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

Från PHP

Använd Rpc::call() för anrop mellan block på serversidan. Det är användbart när en RPC-funktion behöver samordna anrop till andra block:

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-slutpunkt

I bakgrunden mappas varje funktion till en REST-rutt:

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

Begärandekropp: { "params": { ... } }

Svar: Returvärdet från funktionen PHP som JSON.

Du kan anropa dessa slutpunkter direkt från valfri HTTP-klient, men bs.fn() rekommenderas eftersom den hanterar nonce-autentisering automatiskt.

Hooks

Åtgärder körs före och efter varje RPC-anrop, både från REST och PHP. Alla hooks får en enda $params-array:

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

Filter

Ändra eller lägg till funktioner programmatiskt utifrån blocket:

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

När du ska använda RPC respektive databas

db.php genererar automatiskt CRUD-slutpunkter från ett schema. Använd det när du behöver standardoperationer för att skapa, läsa, uppdatera och ta bort med validering.

rpc.php är till för anpassad logik: skicka e-post, anropa externa API:er, sammanställa data från flera scheman, köra komplexa frågor eller hantera sådant som inte passar CRUD-mönstret.

Systemen är oberoende och kompletterar varandra. Många block använder båda: db.php för datamodellen och rpc.php för affärslogiken ovanpå den.