RPC
RPC (Remote Procedure Call), bloğunuzda PHP işlevleri tanımlamanıza ve bunları önyüzden çağırmanıza olanak tanır. REST API rotalarını elle kaydetmek, denetleyiciler oluşturmak ve fetch çağrılarını bağlamak yerine rpc.php içinde bir işlev yazıp bs.fn() ile çağırırsınız. Blockstudio uç nokta yönlendirmesini, kimlik doğrulamayı, nonce doğrulamasını ve JSON serileştirmesini halleder.
Bu düzen tRPC yaklaşımından esinlenmiştir: yordamları sunucu tarafında tanımlayın, tür denetimli bir yardımcıyla istemciden çağırın. URL oluşturma veya elle fetch standart kod yazma gerekmez.
Nasıl çalışır
- Blok dizininizde
rpc.phpoluşturursunuz - Adlandırılmış işlevlerden oluşan bir ilişkisel dizi döndürür
- Blockstudio her işlev için bir REST uç noktası kaydeder
bs.fn()istemcisi bunları adlarıyla çağırır- Parametreler gönderilir, JSON döner
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php ← your server functions live here
├── script-inline.js ← call them from here
└── style.css
İşlevleri tanımlama
Döndürülen dizideki her anahtar bir işlev adıdır. En basit biçim, doğrudan bir geri çağırma işlevidir:
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];
},
];
Her işlev tek bir $params dizisi alır ve bir dizi döndürmelidir. Dönüş değeri istemciye JSON olarak gönderilir.
Erişim denetimi seçenekleri için callback ve ek anahtarların bulunduğu genişletilmiş biçimi kullanın:
return [
'admin_action' => [
'callback' => function (array $params): array {
return ['ok' => true];
},
'capability' => 'manage_options',
],
];
PHP yerel tanımları
İç içe diziler yerine PHP yerel meta verilerini tercih ediyorsanız, rpc.php öznitelikli yöntemleri olan bir nesne de döndürebilir. Diziler de aynı şekilde çalışır.
<?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];
}
};
Notlar:
- Yöntem adları varsayılan olarak küçük harfli snake case biçimine dönüştürülür; bu nedenle
getStatus(),get_statusolur - Uç nokta adını açıkça belirlemek için
name:kullanın Access::Session, eski'public' => truedavranışıyla eşleşirAccess::Open, eski'public' => 'open'davranışıyla eşleşir- Yalnızca kimliği doğrulanmış kullanıcılara izin veren varsayılan davranış için
access:öğesini belirtmeyin
JavaScript üzerinden çağırma
Blockstudio, RPC işlevlerine sahip blokların bulunduğu sayfalara otomatik olarak bir bs.fn() yardımcısı ekler.
İmza: bs.fn(functionName, params?, blockName?) -> Promise
Blok adını aktarma
Üçüncü bağımsız değişkeni belirtmediğinizde bs.fn(), document.currentScript öğesinin data-block özniteliğine geri döner. Blockstudio hem script.js hem de satır içi komut dosyalarını (script-inline.js veya script.inline.js) <script type="module"> etiketleri olarak yazdırır ve modül komut dosyalarının document.currentScript değeri yoktur. Bu nedenle blok komut dosyalarında blok adını üçüncü bağımsız değişken olarak aktarın:
const posts = await bs.fn('load_more', { offset: 10 }, 'my-theme/blog-feed');
Aksi hâlde çağrı bs.fn: block name required hatası verir.
Hata işleme
bs.fn(), HTTP durumu ne olursa olsun ayrıştırılmış JSON gövdesiyle sonuçlanır. Bir işlev WP_Error döndürdüğünde promise, code, message ve data değerlerini içeren bir nesneyle sonuçlanır; bu nedenle code olup olmadığını denetleyin:
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');
if (result.code) {
console.error('RPC failed:', result.message);
}
Promise yalnızca isteğin kendisi başarısız olduğunda veya yanıt JSON olmadığında reddedilir.
Interactivity API ile
RPC, WordPress Interactivity API ile doğal biçimde birlikte çalışır. Depo eylemleriniz sunucu işlevlerini çağırır ve yanıtla reaktif durumu günceller. UI otomatik olarak güncellenir:
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>
Erişim denetimi
Varsayılan olarak işlevler, kimliği doğrulanmış (oturum açmış) bir kullanıcı gerektirir. Bu, WordPress uç noktalarının varsayılan olarak korunduğu REST kurallarıyla uyumludur.
Herkese açık işlevler
CSRF korumasıyla kimlik doğrulaması gerektirmeyen erişime izin verin:
return [
'get_count' => [
'callback' => function (array $params): array {
return ['count' => wp_count_posts()->publish];
},
'public' => true, // public + CSRF protected via X-BS-Token
],
];
Önbelleğe Alınmış Sayfalar
bs.fn(), güncel kimlik bilgilerini önbelleğe alınmayan aynı kaynaklı POST /wp-json/blockstudio/v1/client/credentials uç noktasından alır. Süresi dolan WordPress nonce’ları ve Blockstudio CSRF belirteçleri sayfa HTML içinde saklanmaz; böylece harici bir sayfa önbelleği 24 saatten eski HTML sunsa bile genel çağrılar çalışmaya devam eder.
Yenileme gerektiğinde yapılır: API çağrısı yapılmadan bir sayfanın yüklenmesi kimlik bilgisi isteği oluşturmaz. RPC ve veritabanı istemcileri yenileme işlemini paylaşır, beş dakikalık kullanımdan sonra kimlik bilgilerini yeniler ve süresi dolmuş bir nonce veya CSRF belirteci için bir kez yeniden dener. Yetenek hataları ve uygulama hataları yeniden denenmez. Kimlik doğrulama, mevcut ziyaretçinin WordPress oturum açma çerezini kullanır; kimlik bilgilerini yenilemek özel işlevlere erişim sağlamaz. Kimlik bilgisi uç noktasını tüm CDN veya proxy önbelleklerinin dışında tutun; yanıtları açıkça private, no-store olarak işaretlenir.
Açık işlevler
Herhangi bir belirteç olmadan tamamen açık erişim gerektiren webhook’lar veya harici API geri çağırmaları için:
return [
'webhook' => [
'callback' => function (array $params): array {
// Called by an external service
return ['received' => true];
},
'public' => 'open', // no CSRF, no auth
],
];
Yetenekler
Erişimi belirli WordPress yetenekleriyle sınırlandırın. Tek bir yetenek için dize, kullanıcının herhangi birine sahip olmasının yeterli olduğu durumlarda ise dizi kullanın:
return [
'save_draft' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => 'edit_posts',
],
'moderate' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => ['edit_others_posts', 'manage_options'],
],
];
HTTP yöntemleri
Varsayılan olarak işlevler yalnızca POST isteklerini kabul eder. Bu, durumu değiştiren işlemler için en güvenli varsayılandır. Gerektiğinde ek yöntemlere izin verin:
return [
'get_status' => [
'callback' => function (array $params): array {
return ['status' => 'ok'];
},
'methods' => ['GET', 'POST'],
],
];
Bloklar arası çağırma
JavaScript üzerinden
Herhangi bir blok, blok adını üçüncü bağımsız değişken olarak aktararak başka bir bloktaki işlevleri çağırabilir. Böylece bloklar arasında bileşim kurabilirsiniz:
// Block A calling a function defined in Block B
const result = await bs.fn('load_more', { offset: 0 }, 'my-theme/blog-feed');
PHP üzerinden
Sunucu tarafında bloklar arası çağrılar için Rpc::call() kullanın. Bir RPC işlevinin diğer bloklara yapılan çağrıları düzenlemesi gerektiğinde işe yarar:
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 uç noktası
Arka planda her işlev bir REST rotasına eşlenir:
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}
İstek gövdesi: { "params": { ... } }
Yanıt: PHP işlevinin JSON olarak döndürdüğü değer.
Bu uç noktaları herhangi bir HTTP istemcisinden doğrudan çağırabilirsiniz; ancak nonce kimlik doğrulamasını otomatik olarak hallettiği için bs.fn() kullanılması önerilir.
Kancalar
Eylemler, hem REST hem de PHP kaynaklı her RPC çağrısından önce ve sonra tetiklenir. Tüm kancalar tek bir $params dizisi alır:
| Kanca | Parametreler |
|---|---|
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.
});
Filtre
Blok dışından işlevleri programlı olarak değiştirin veya ekleyin:
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;
});
RPC ile Veritabanını ne zaman kullanmalı
rpc.php özel mantık içindir: e-posta gönderme, harici API’leri çağırma, şemalar arasında veri toplama, karmaşık sorgular çalıştırma veya CRUD düzenine uymayan diğer işlemler.
İki sistem birbirinden bağımsızdır ve birbirini tamamlar. Birçok blok ikisini de kullanır: veri modeli için db.php, bu model üzerine kurulan iş mantığı için rpc.php.