Ugrás a tartalomhoz

RPC

A RPC (Remote Procedure Call, távoli eljáráshívás) segítségével PHP függvényeket definiálhat a blokkjában, és meghívhatja őket a frontendről. A REST API útvonalak kézi regisztrálása, vezérlők létrehozása és a fetch hívások összekötése helyett írjon egy függvényt a rpc.php-ben, majd hívja meg a bs.fn() segítségével. A Blockstudio kezeli a végpontok útvonalát, a hitelesítést, a nonce-ellenőrzést és a JSON szerializálását.

A minta a tRPC megoldásából ered: definiálja az eljárásokat a szerveren, majd egy típusos segédfüggvénnyel hívja meg őket a kliensről. Nincs szükség URL létrehozására vagy kézi fetch sablonkódra.

Működés

  1. Hozzon létre rpc.php-t a blokk könyvtárában
  2. Ez névvel ellátott függvények asszociatív tömbjét adja vissza
  3. A Blockstudio minden függvényhez regisztrál egy REST végpontot
  4. A bs.fn() kliens név szerint hívja meg őket
  5. A paraméterek bemenetként érkeznek, JSON pedig kimenetként tér vissza
Kód
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php             ← your server functions live here
├── script-inline.js    ← call them from here
└── style.css

Függvények definiálása

A visszaadott tömb minden kulcsa egy függvény neve. A legegyszerűbb forma a közvetlen visszahívási függvény:

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

Minden függvény egyetlen $params tömböt kap, és egy tömböt kell visszaadnia. A visszatérési értéket a rendszer JSON formájában küldi el a kliensnek.

A hozzáférés-vezérlési beállításokhoz használja a kibővített formátumot a callback elemmel és további kulcsokkal:

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

PHP-natív definíciók

Ha a beágyazott tömbök helyett a PHP natív metaadatait részesíti előnyben, a rpc.php attribútumokkal ellátott metódusokat tartalmazó objektumot is visszaadhat. A tömbök továbbra is ugyanúgy működnek.

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

Megjegyzések:

  • A metódusnevek alapértelmezés szerint kisbetűs snake case formára normalizálódnak, ezért a getStatus() névből get_status lesz
  • A name: segítségével felülírhatja a végpont nevét
  • A Access::Session a régi 'public' => true működésének felel meg
  • A Access::Open a régi 'public' => 'open' működésének felel meg
  • Hagyja ki a access: elemet az alapértelmezett, csak hitelesített felhasználóknak szóló működéshez

Hívás JavaScript-ből

A Blockstudio automatikusan beilleszt egy bs.fn() segédfüggvényt azokra az oldalakra, amelyeken RPC függvényeket tartalmazó blokkok vannak.

Aláírás: bs.fn(functionName, params?, blockName?) -> Promise

A blokk nevének megadása

Ha kihagyja a harmadik argumentumot, a bs.fn() a document.currentScript data-block attribútumára vált vissza. A Blockstudio a script.js értékét és a beágyazott szkripteket (script-inline.js vagy script.inline.js) is <script type="module"> címkékként jeleníti meg, a modulszkripteknek pedig nincs document.currentScript attribútumuk. Ezért a blokkszkriptekben harmadik argumentumként adja meg a blokk nevét:

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

Enélkül a hívás bs.fn: block name required hibát dob.

Hibakezelés

A bs.fn() a feldolgozott JSON törzzsel teljesül, függetlenül a HTTP állapotától. Ha egy függvény WP_Error értéket ad vissza, az ígéret egy olyan objektummal teljesül, amely tartalmazza annak code, message és data értékét, ezért ellenőrizze a code értéket:

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

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

Az ígéret csak akkor utasítódik el, ha maga a kérés sikertelen, vagy a válasz nem JSON.

Az Interactivity API használatával

A RPC természetesen együttműködik az WordPress Interactivity API megoldással. Az áruház műveletei szerverfüggvényeket hívnak, és a válasz alapján frissítik a reaktív állapotot. A UI automatikusan frissül:

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>

Hozzáférés-vezérlés

Alapértelmezés szerint a függvények hitelesített (bejelentkezett) felhasználót igényelnek. Ez megfelel a WordPress konvencióinak, amelyek szerint a REST végpontok alapértelmezés szerint védettek.

Nyilvános függvények

Névtelen hozzáférés engedélyezése CSRF-védelemmel:

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

Gyorsítótárazott oldalak

A bs.fn() friss hitelesítő adatokat kér le a gyorsítótárazásból kizárt, azonos eredetű POST /wp-json/blockstudio/v1/client/credentials végpontról. A lejáró WordPress nonce-okat és Blockstudio CSRF-tokeneket a rendszer nem tárolja az oldal HTML részében, így a nyilvános hívások akkor is működnek, ha egy külső oldalgyorsítótár 24 óránál régebbi HTML adatot szolgál ki.

A frissítés igény szerinti: ha egy oldal betöltésekor nem történik API hívás, a rendszer nem kér hitelesítő adatokat. A RPC és az adatbázis-kliensek közösen végzik a frissítést, öt perc használat után megújítják a hitelesítő adatokat, és lejárt nonce vagy CSRF-token esetén egyszer újrapróbálkoznak. A képességellenőrzési hibákkal és az alkalmazáshibákkal nem próbálkoznak újra. A hitelesítés továbbra is a látogató aktuális WordPress bejelentkezési sütijét követi; a hitelesítő adatok frissítése nem biztosít hozzáférést a privát függvényekhez. Tartsa a hitelesítőadat-végpontot minden CDN vagy proxy gyorsítótárán kívül; a válaszai kifejezetten private, no-store jelölést kapnak.

Nyitott függvények

Webhookokhoz vagy külső API visszahívásokhoz, amelyeknek token nélkül, teljesen nyitott hozzáférésre van szükségük:

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

Képességek

Korlátozza a hozzáférést bizonyos WordPress képességekre. Egyetlen képességhez használjon szöveget, vagy olyan tömböt, amelyben a felhasználónak bármelyik képességre szüksége van:

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 metódusok

Alapértelmezés szerint a függvények csak POST kéréseket fogadnak. Ez a legbiztonságosabb alapértelmezés az állapotot módosító műveletekhez. Szükség esetén további metódusokat is engedélyezhet:

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

Hívások blokkok között

Hívás JavaScript-ből

Bármelyik blokk meghívhatja egy másik blokk függvényeit, ha harmadik argumentumként megadja annak nevét. Ez lehetővé teszi a blokkok összekapcsolását:

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

Hívás PHP-ből

Blokkok közötti szerveroldali hívásokhoz használja a Rpc::call()-t. Ez akkor hasznos, ha egy RPC függvénynek más blokkok hívásait kell összehangolnia:

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 végpont

A háttérben minden függvény egy REST útvonalhoz van rendelve:

Kód
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}

Kérés törzse: { "params": { ... } }

Válasz: A PHP függvény visszatérési értéke JSON formátumban.

Ezeket a végpontokat közvetlenül bármelyik HTTP kliensből meghívhatja, de a bs.fn() használata ajánlott, mert automatikusan kezeli a nonce-hitelesítést.

Hookok

A műveletek minden RPC hívás előtt és után lefutnak, mind a REST, mind a PHP esetén. Minden hook egyetlen $params tömböt kap:

Hook Paraméterek
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.
});

Szűrő

Függvények módosítása vagy hozzáadása programozottan, a blokkon kívülről:

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

Mikor használja a RPC-t és mikor az adatbázist?

A db.php automatikusan CRUD-végpontokat hoz létre a sémából. Akkor használja, ha szabványos létrehozási, olvasási, frissítési és törlési műveletekre van szüksége érvényesítéssel.

A rpc.php egyéni logikához való: e-mailek küldéséhez, külső API-k hívásához, sémák közötti adatok összesítéséhez, összetett lekérdezések futtatásához vagy bármihez, ami nem illik a CRUD-mintába.

A két rendszer egymástól független, mégis kiegészíti egymást. Sok blokk mindkettőt használja: a db.php-t az adatmodellhez, a rpc.php-t pedig az arra épülő üzleti logikához.