Μετάβαση στο περιεχόμενο

RPC

Το RPC (Remote Procedure Call) σάς επιτρέπει να ορίζετε συναρτήσεις PHP στο μπλοκ σας και να τις καλείτε από το frontend. Αντί να καταχωρίζετε χειροκίνητα διαδρομές REST API, να δημιουργείτε controllers και να συνδέετε κλήσεις fetch, γράφετε μια συνάρτηση στο rpc.php και την καλείτε με το bs.fn(). Το Blockstudio αναλαμβάνει τη δρομολόγηση του endpoint, την πιστοποίηση, την επικύρωση nonce και τη σειριοποίηση JSON.

Το μοτίβο είναι εμπνευσμένο από το tRPC: ορίστε τις διαδικασίες στην πλευρά του διακομιστή και καλέστε τις από τον client με έναν helper με τυποποίηση. Χωρίς κατασκευή URL και χωρίς τυπικό κώδικα fetch.

Πώς λειτουργεί

  1. Δημιουργείτε το rpc.php στον κατάλογο του μπλοκ σας
  2. Επιστρέφει έναν συσχετιστικό πίνακα με επώνυμες συναρτήσεις
  3. Το Blockstudio καταχωρίζει ένα endpoint REST για κάθε συνάρτηση
  4. Ο client bs.fn() τις καλεί με το όνομά τους
  5. Οι παράμετροι εισάγονται και επιστρέφεται το 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:

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

Κάθε συνάρτηση λαμβάνει έναν πίνακα $params και πρέπει να επιστρέφει έναν πίνακα. Η τιμή επιστροφής αποστέλλεται στον client ως JSON.

Για επιλογές ελέγχου πρόσβασης, χρησιμοποιήστε την εκτεταμένη μορφή με callback και πρόσθετα κλειδιά:

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

Ορισμοί εγγενείς στο PHP

Αν προτιμάτε μεταδεδομένα εγγενή στο PHP αντί για ένθετους πίνακες, το rpc.php μπορεί επίσης να επιστρέψει ένα αντικείμενο με μεθόδους που έχουν χαρακτηριστικά. Οι πίνακες εξακολουθούν να λειτουργούν ακριβώς με τον ίδιο τρόπο.

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. Επομένως, στα σενάρια μπλοκ περάστε το όνομα του μπλοκ ως τρίτο όρισμα:

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

JavaScript
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 ενημερώνεται αυτόματα:

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>

Έλεγχος πρόσβασης

Από προεπιλογή, οι συναρτήσεις απαιτούν πιστοποιημένο χρήστη (συνδεδεμένο). Αυτό συμβαδίζει με τις συμβάσεις του WordPress, όπου τα endpoint REST προστατεύονται από προεπιλογή.

Δημόσιες συναρτήσεις

Επιτρέψτε πρόσβαση χωρίς πιστοποίηση με προστασία 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
    ],
];

Σελίδες σε προσωρινή μνήμη

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

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

Δυνατότητες

Περιορίστε την πρόσβαση σε συγκεκριμένες δυνατότητες WordPress. Χρησιμοποιήστε συμβολοσειρά για μία δυνατότητα ή πίνακα όταν ο χρήστης χρειάζεται οποιαδήποτε από αυτές:

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

Από προεπιλογή, οι συναρτήσεις δέχονται μόνο αιτήματα POST. Αυτή είναι η ασφαλέστερη προεπιλογή για λειτουργίες που τροποποιούν την κατάσταση. Επιτρέψτε πρόσθετες μεθόδους όταν χρειάζεται:

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

Κλήσεις μεταξύ μπλοκ

Από το JavaScript

Κάθε μπλοκ μπορεί να καλεί συναρτήσεις οποιουδήποτε άλλου μπλοκ, περνώντας το όνομα του μπλοκ ως τρίτο όρισμα. Έτσι επιτυγχάνεται η σύνθεση μεταξύ μπλοκ:

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 χρειάζεται να συντονίσει κλήσεις σε άλλα μπλοκ:

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

Στο παρασκήνιο, κάθε συνάρτηση αντιστοιχεί σε μια διαδρομή 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
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.
});

Φίλτρο

Τροποποιήστε ή προσθέστε συναρτήσεις προγραμματιστικά από έξω από το μπλοκ:

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 αντί για τη βάση δεδομένων

Το db.php δημιουργεί αυτόματα endpoint CRUD από ένα σχήμα. Χρησιμοποιήστε το όταν χρειάζεστε τυπικές λειτουργίες δημιουργίας/ανάγνωσης/ενημέρωσης/διαγραφής με επικύρωση.

Το rpc.php προορίζεται για προσαρμοσμένη λογική: αποστολή email, κλήση εξωτερικών API, συνάθροιση δεδομένων από πολλά σχήματα, εκτέλεση σύνθετων ερωτημάτων ή οτιδήποτε δεν ταιριάζει στο μοτίβο CRUD.

Τα δύο συστήματα είναι ανεξάρτητα και συμπληρωματικά. Πολλά μπλοκ χρησιμοποιούν και τα δύο: το db.php για το μοντέλο δεδομένων και το rpc.php για την επιχειρησιακή λογική που βασίζεται σε αυτό.