İçeriğe geç

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

  1. Blok dizininizde rpc.php oluşturursunuz
  2. Adlandırılmış işlevlerden oluşan bir ilişkisel dizi döndürür
  3. Blockstudio her işlev için bir REST uç noktası kaydeder
  4. bs.fn() istemcisi bunları adlarıyla çağırır
  5. Parametreler gönderilir, JSON döner
Kod
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:

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

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:

PHP
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
<?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_status olur
  • Uç nokta adını açıkça belirlemek için name: kullanın
  • Access::Session, eski 'public' => true davranışıyla eşleşir
  • Access::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:

JavaScript
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:

JavaScript
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:

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>

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:

PHP
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:

PHP
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:

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

PHP
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:

JavaScript
// 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:

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 uç noktası

Arka planda her işlev bir REST rotasına eşlenir:

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

Filtre

Blok dışından işlevleri programlı olarak değiştirin veya ekleyin:

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

RPC ile Veritabanını ne zaman kullanmalı

db.php, bir şemadan otomatik olarak CRUD uç noktaları oluşturur. Doğrulama içeren standart oluşturma/okuma/güncelleme/silme işlemlerine ihtiyaç duyduğunuzda kullanın.

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.