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
- Anda membuat
rpc.phpdi direktori blok - Hasilnya berupa array asosiatif berisi fungsi bernama
- Blockstudio mendaftarkan endpoint REST untuk setiap fungsi
- Klien
bs.fn()memanggilnya berdasarkan nama - Parameter masuk, JSON keluar
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:
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:
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
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()menjadiget_status - Gunakan
name:untuk menetapkan nama endpoint secara eksplisit Access::Sessionsesuai dengan perilaku'public' => trueyang lamaAccess::Opensesuai 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:
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:
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:
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;
},
},
});
<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:
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:
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:
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:
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:
// 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:
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:
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 |
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:
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.