RPC
Το RPC (Remote Procedure Call) σάς επιτρέπει να ορίζετε συναρτήσεις PHP στο μπλοκ σας και να τις καλείτε από το frontend. Αντί να καταχωρίζετε χειροκίνητα διαδρομές REST API, να δημιουργείτε controllers και να συνδέετε κλήσεις fetch, γράφετε μια συνάρτηση στο rpc.php και την καλείτε με το bs.fn(). Το Blockstudio αναλαμβάνει τη δρομολόγηση του endpoint, την πιστοποίηση, την επικύρωση nonce και τη σειριοποίηση JSON.
Το μοτίβο είναι εμπνευσμένο από το tRPC: ορίστε τις διαδικασίες στην πλευρά του διακομιστή και καλέστε τις από τον client με έναν helper με τυποποίηση. Χωρίς κατασκευή URL και χωρίς τυπικό κώδικα fetch.
Πώς λειτουργεί
- Δημιουργείτε το
rpc.phpστον κατάλογο του μπλοκ σας - Επιστρέφει έναν συσχετιστικό πίνακα με επώνυμες συναρτήσεις
- Το Blockstudio καταχωρίζει ένα endpoint REST για κάθε συνάρτηση
- Ο client
bs.fn()τις καλεί με το όνομά τους - Οι παράμετροι εισάγονται και επιστρέφεται το JSON
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php ← your server functions live here
├── script-inline.js ← call them from here
└── style.css
Ορισμός συναρτήσεων
Κάθε κλειδί στον πίνακα που επιστρέφεται είναι ένα όνομα συνάρτησης. Η απλούστερη μορφή είναι μια άμεση callback:
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];
},
];
Κάθε συνάρτηση λαμβάνει έναν πίνακα $params και πρέπει να επιστρέφει έναν πίνακα. Η τιμή επιστροφής αποστέλλεται στον client ως JSON.
Για επιλογές ελέγχου πρόσβασης, χρησιμοποιήστε την εκτεταμένη μορφή με callback και πρόσθετα κλειδιά:
return [
'admin_action' => [
'callback' => function (array $params): array {
return ['ok' => true];
},
'capability' => 'manage_options',
],
];
Ορισμοί εγγενείς στο PHP
Αν προτιμάτε μεταδεδομένα εγγενή στο PHP αντί για ένθετους πίνακες, το rpc.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];
}
};
Σημειώσεις:
- Τα ονόματα μεθόδων μετατρέπονται από προεπιλογή σε πεζά γράμματα και snake case, επομένως το
getStatus()γίνεταιget_status - Χρησιμοποιήστε το
name:για να παρακάμψετε ρητά το όνομα του endpoint - Το
Access::Sessionαντιστοιχεί στην παλιά συμπεριφορά'public' => true - Το
Access::Openαντιστοιχεί στην παλιά συμπεριφορά'public' => 'open' - Παραλείψτε το
access:για την προεπιλεγμένη συμπεριφορά που επιτρέπει μόνο πιστοποιημένους χρήστες
Κλήση από το JavaScript
Το Blockstudio εισάγει αυτόματα έναν helper bs.fn() στις σελίδες που περιέχουν μπλοκ με συναρτήσεις RPC.
Υπογραφή: bs.fn(functionName, params?, blockName?) -> Promise
Μεταβίβαση του ονόματος του μπλοκ
Το bs.fn() χρησιμοποιεί ως εναλλακτική την ιδιότητα data-block του document.currentScript όταν παραλείπετε το τρίτο όρισμα. Το Blockstudio εκτυπώνει τόσο τα script.js όσο και τα ενσωματωμένα σενάρια (script-inline.js ή script.inline.js) ως ετικέτες <script type="module">, ενώ τα αρθρωτά σενάρια δεν έχουν document.currentScript. Επομένως, στα σενάρια μπλοκ περάστε το όνομα του μπλοκ ως τρίτο όρισμα:
const posts = await bs.fn('load_more', { offset: 10 }, 'my-theme/blog-feed');
Χωρίς αυτό, η κλήση προκαλεί bs.fn: block name required.
Διαχείριση σφαλμάτων
Το bs.fn() επιλύεται με το σώμα JSON που έχει αναλυθεί, ανεξάρτητα από την κατάσταση HTTP. Όταν μια συνάρτηση επιστρέφει ένα WP_Error, το promise επιλύεται με ένα αντικείμενο που περιέχει το code, το message και το data της, επομένως ελέγξτε το code:
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');
if (result.code) {
console.error('RPC failed:', result.message);
}
Το promise απορρίπτεται μόνο όταν αποτυγχάνει το ίδιο το αίτημα ή όταν η απόκριση δεν είναι JSON.
Με το API Interactivity
Το RPC συνδυάζεται φυσικά με το WordPress Interactivity API. Οι ενέργειες του store σας καλούν συναρτήσεις διακομιστή και ενημερώνουν την αντιδραστική κατάσταση με την απόκριση. Το UI ενημερώνεται αυτόματα:
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>
Έλεγχος πρόσβασης
Από προεπιλογή, οι συναρτήσεις απαιτούν πιστοποιημένο χρήστη (συνδεδεμένο). Αυτό συμβαδίζει με τις συμβάσεις του WordPress, όπου τα endpoint REST προστατεύονται από προεπιλογή.
Δημόσιες συναρτήσεις
Επιτρέψτε πρόσβαση χωρίς πιστοποίηση με προστασία CSRF:
return [
'get_count' => [
'callback' => function (array $params): array {
return ['count' => wp_count_posts()->publish];
},
'public' => true, // public + CSRF protected via X-BS-Token
],
];
Σελίδες σε προσωρινή μνήμη
Το bs.fn() ανακτά νέα διαπιστευτήρια από το endpoint ίδιας προέλευσης POST /wp-json/blockstudio/v1/client/credentials, το οποίο δεν αποθηκεύεται προσωρινά. Τα λήγοντα nonce WordPress και διακριτικά CSRF Blockstudio δεν αποθηκεύονται στο HTML της σελίδας, οπότε οι δημόσιες κλήσεις εξακολουθούν να λειτουργούν όταν μια εξωτερική προσωρινή μνήμη σελίδων παρέχει HTML παλαιότερο από 24 ώρες.
Η ανανέωση γίνεται μόνο όταν χρειάζεται: η φόρτωση μιας σελίδας χωρίς κλήση σε API δεν προκαλεί αίτημα διαπιστευτηρίων. Τα RPC και τα clients βάσης δεδομένων μοιράζονται την ανανέωση, ανανεώνουν τα διαπιστευτήρια μετά από πέντε λεπτά χρήσης και επαναλαμβάνουν μία φορά την κλήση για ληγμένο nonce ή διακριτικό CSRF. Οι αποτυχίες δικαιωμάτων και τα σφάλματα εφαρμογής δεν οδηγούν σε επανάληψη. Ο έλεγχος ταυτότητας εξακολουθεί να βασίζεται στο cookie σύνδεσης WordPress του τρέχοντος επισκέπτη· η ανανέωση διαπιστευτηρίων δεν παρέχει πρόσβαση σε ιδιωτικές συναρτήσεις. Κρατήστε το endpoint διαπιστευτηρίων έξω από κάθε προσωρινή μνήμη CDN ή proxy· οι απαντήσεις του επισημαίνονται ρητά ως private, no-store.
Ανοιχτές συναρτήσεις
Για webhook ή εξωτερικές κλήσεις API που χρειάζονται εντελώς ανοιχτή πρόσβαση χωρίς token:
return [
'webhook' => [
'callback' => function (array $params): array {
// Called by an external service
return ['received' => true];
},
'public' => 'open', // no CSRF, no auth
],
];
Δυνατότητες
Περιορίστε την πρόσβαση σε συγκεκριμένες δυνατότητες WordPress. Χρησιμοποιήστε συμβολοσειρά για μία δυνατότητα ή πίνακα όταν ο χρήστης χρειάζεται οποιαδήποτε από αυτές:
return [
'save_draft' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => 'edit_posts',
],
'moderate' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => ['edit_others_posts', 'manage_options'],
],
];
Μέθοδοι HTTP
Από προεπιλογή, οι συναρτήσεις δέχονται μόνο αιτήματα POST. Αυτή είναι η ασφαλέστερη προεπιλογή για λειτουργίες που τροποποιούν την κατάσταση. Επιτρέψτε πρόσθετες μεθόδους όταν χρειάζεται:
return [
'get_status' => [
'callback' => function (array $params): array {
return ['status' => 'ok'];
},
'methods' => ['GET', 'POST'],
],
];
Κλήσεις μεταξύ μπλοκ
Από το JavaScript
Κάθε μπλοκ μπορεί να καλεί συναρτήσεις οποιουδήποτε άλλου μπλοκ, περνώντας το όνομα του μπλοκ ως τρίτο όρισμα. Έτσι επιτυγχάνεται η σύνθεση μεταξύ μπλοκ:
// Block A calling a function defined in Block B
const result = await bs.fn('load_more', { offset: 0 }, 'my-theme/blog-feed');
Από το PHP
Χρησιμοποιήστε το Rpc::call() για κλήσεις μεταξύ μπλοκ στην πλευρά του διακομιστή. Αυτό είναι χρήσιμο όταν μια συνάρτηση RPC χρειάζεται να συντονίσει κλήσεις σε άλλα μπλοκ:
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
Στο παρασκήνιο, κάθε συνάρτηση αντιστοιχεί σε μια διαδρομή REST:
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}
Σώμα αιτήματος: { "params": { ... } }
Απόκριση: Η τιμή που επιστρέφει η συνάρτηση PHP ως JSON.
Μπορείτε να καλείτε αυτά τα endpoint απευθείας από οποιονδήποτε client HTTP, αλλά συνιστάται το bs.fn(), καθώς διαχειρίζεται αυτόματα την πιστοποίηση nonce.
Άγκιστρα
Οι ενέργειες εκτελούνται πριν και μετά από κάθε κλήση RPC, τόσο από το REST όσο και από το PHP. Όλα τα άγκιστρα λαμβάνουν έναν πίνακα $params:
| Άγκιστρο | Παράμετροι |
|---|---|
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.
});
Φίλτρο
Τροποποιήστε ή προσθέστε συναρτήσεις προγραμματιστικά από έξω από το μπλοκ:
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 αντί για τη βάση δεδομένων
Το db.php δημιουργεί αυτόματα endpoint CRUD από ένα σχήμα. Χρησιμοποιήστε το όταν χρειάζεστε τυπικές λειτουργίες δημιουργίας/ανάγνωσης/ενημέρωσης/διαγραφής με επικύρωση.
Το rpc.php προορίζεται για προσαρμοσμένη λογική: αποστολή email, κλήση εξωτερικών API, συνάθροιση δεδομένων από πολλά σχήματα, εκτέλεση σύνθετων ερωτημάτων ή οτιδήποτε δεν ταιριάζει στο μοτίβο CRUD.
Τα δύο συστήματα είναι ανεξάρτητα και συμπληρωματικά. Πολλά μπλοκ χρησιμοποιούν και τα δύο: το db.php για το μοντέλο δεδομένων και το rpc.php για την επιχειρησιακή λογική που βασίζεται σε αυτό.