Lewati ke konten

RPC

RPC (Remote Procedure Call) memungkinkan Anda mendefinisikan fungsi PHP di blok dan memanggilnya dari frontend. Alih-alih mendaftarkan rute REST API secara manual, membuat controller, dan menghubungkan pemanggilan fetch, Anda menulis fungsi di rpc.php lalu memanggilnya dengan bs.fn(). Blockstudio menangani perutean endpoint, autentikasi, validasi nonce, dan serialisasi JSON.

Pola ini terinspirasi tRPC: definisikan prosedur di sisi server, lalu panggil dari klien dengan helper bertipe. Tanpa membuat URL, tanpa boilerplate fetch manual.

Cara kerjanya

  1. Anda membuat rpc.php di direktori blok
  2. Hasilnya berupa array asosiatif berisi fungsi bernama
  3. Blockstudio mendaftarkan endpoint REST untuk setiap fungsi
  4. Klien bs.fn() memanggilnya berdasarkan nama
  5. Parameter masuk, JSON keluar
Kode
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php             ← your server functions live here
├── script-inline.js    ← call them from here
└── style.css

Mendefinisikan fungsi

Setiap kunci dalam array hasil adalah nama fungsi. Bentuk paling sederhana adalah callback langsung:

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

Setiap fungsi menerima satu array $params dan sebaiknya mengembalikan array. Nilai hasil tersebut dikirim ke klien sebagai JSON.

Untuk opsi kontrol akses, gunakan format yang diperluas dengan callback dan kunci tambahan:

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

Definisi native PHP

Jika Anda lebih memilih metadata native PHP daripada array bersarang, rpc.php juga dapat mengembalikan objek dengan metode beratribut. Array tetap berfungsi dengan cara yang sama.

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

Catatan:

  • Secara default, nama metode dinormalisasi menjadi snake case huruf kecil, sehingga getStatus() menjadi get_status
  • Gunakan name: untuk menetapkan nama endpoint secara eksplisit
  • Access::Session sesuai dengan perilaku 'public' => true yang lama
  • Access::Open sesuai dengan perilaku 'public' => 'open' yang lama
  • Hilangkan access: untuk perilaku default yang hanya mengizinkan pengguna terautentikasi

Memanggil dari JavaScript

Blockstudio otomatis menyisipkan helper bs.fn() pada halaman yang memiliki blok dengan fungsi RPC.

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

Meneruskan nama blok

bs.fn() menggunakan atribut data-block dari document.currentScript sebagai nilai cadangan jika argumen ketiga tidak diberikan. Blockstudio mencetak script.js dan skrip inline (script-inline.js atau script.inline.js) sebagai tag <script type="module">, dan skrip modul tidak memiliki document.currentScript. Karena itu, di skrip blok, teruskan nama blok sebagai argumen ketiga:

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

Tanpanya, pemanggilan akan memunculkan bs.fn: block name required.

Penanganan error

bs.fn() menghasilkan body JSON yang telah diurai, apa pun status HTTP. Jika fungsi mengembalikan WP_Error, promise menghasilkan objek yang berisi code, message, dan data. Jadi, periksa code:

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

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

Promise hanya ditolak jika permintaan itu sendiri gagal atau respons bukan JSON.

Dengan API Interactivity

RPC berpadu secara alami dengan WordPress Interactivity API. Action store Anda memanggil fungsi server dan memperbarui status reaktif dengan responsnya. UI diperbarui secara otomatis:

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>

Kontrol akses

Secara default, fungsi memerlukan pengguna terautentikasi (yang sudah masuk). Ini sesuai dengan konvensi WordPress, yaitu endpoint REST secara default dilindungi.

Fungsi publik

Izinkan akses tanpa autentikasi dengan perlindungan 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
    ],
];

Halaman yang Di-cache

bs.fn() mengambil kredensial terbaru dari endpoint POST /wp-json/blockstudio/v1/client/credentials same-origin yang tidak di-cache. Nonce WordPress dan token CSRF Blockstudio yang kedaluwarsa tidak disimpan dalam HTML halaman, sehingga panggilan publik tetap berfungsi saat cache halaman eksternal menyajikan HTML yang berusia lebih dari 24 jam.

Refresh berlangsung secara tertunda: memuat halaman tanpa memanggil API tidak akan membuat permintaan kredensial. RPC dan klien basis data berbagi proses refresh, memperbarui kredensial setelah digunakan selama lima menit, dan mencoba ulang satu kali jika nonce atau token CSRF kedaluwarsa. Kegagalan kapabilitas dan kesalahan aplikasi tidak dicoba ulang. Autentikasi tetap mengikuti cookie login WordPress pengunjung saat ini; refresh kredensial tidak memberikan akses ke fungsi privat. Tempatkan endpoint kredensial di luar cache CDN atau proxy; responsnya secara eksplisit ditandai sebagai private, no-store.

Fungsi terbuka

Untuk webhook atau callback API eksternal yang memerlukan akses terbuka sepenuhnya tanpa token:

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

Kapabilitas

Batasi ke kapabilitas WordPress tertentu. Gunakan string untuk satu kapabilitas, atau array jika pengguna cukup memiliki salah satunya:

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

Secara default, fungsi hanya menerima permintaan POST. Ini adalah pilihan default paling aman untuk operasi yang mengubah status. Izinkan metode tambahan bila diperlukan:

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

Pemanggilan lintas blok

Dari JavaScript

Blok mana pun dapat memanggil fungsi di blok lain dengan meneruskan nama blok sebagai argumen ketiga. Ini memungkinkan komposisi antarblok:

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

Dari PHP

Gunakan Rpc::call() untuk pemanggilan lintas blok di sisi server. Ini berguna saat fungsi RPC perlu mengatur pemanggilan ke blok lain:

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 REST

Di balik layar, setiap fungsi dipetakan ke rute REST:

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

Body permintaan: { "params": { ... } }

Respons: Nilai hasil fungsi PHP dalam bentuk JSON.

Anda dapat memanggil endpoint ini langsung dari klien HTTP mana pun, tetapi bs.fn() adalah cara yang disarankan karena menangani autentikasi nonce secara otomatis.

Hook

Action dijalankan sebelum dan sesudah setiap pemanggilan RPC, baik dari REST maupun PHP. Semua hook menerima satu array $params:

Hook Parameter
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

Ubah atau tambahkan fungsi secara terprogram dari luar blok:

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

Kapan menggunakan RPC dibandingkan Database

db.php membuat endpoint CRUD secara otomatis dari skema. Gunakan saat Anda memerlukan operasi buat/baca/perbarui/hapus standar dengan validasi.

rpc.php digunakan untuk logika khusus: mengirim email, memanggil API eksternal, menggabungkan data dari beberapa skema, menjalankan kueri kompleks, atau hal lain yang tidak sesuai dengan pola CRUD.

Kedua sistem ini berdiri sendiri dan saling melengkapi. Banyak blok menggunakan keduanya: db.php untuk model data dan rpc.php untuk logika bisnis di atasnya.