انتقل إلى المحتوى

RPC

يتيح RPC (استدعاء الإجراءات عن بُعد) تعريف وظائف PHP في كتلتك واستدعاءها من الواجهة الأمامية. بدلًا من تسجيل مسارات REST API يدويًا، وإنشاء وحدات التحكم وربط استدعاءات fetch، اكتب وظيفة في rpc.php واستدعها باستخدام bs.fn(). يتولى Blockstudio توجيه نقاط النهاية، والمصادقة، والتحقق من nonce، وتسلسل JSON.

هذا النمط مستوحى من tRPC: عرّف الإجراءات على الخادم، واستدعها من العميل باستخدام مساعد ذي أنواع. دون إنشاء URL، أو كتابة أكواد fetch تمهيدية يدويًا.

طريقة العمل

  1. أنشئ rpc.php في دليل الكتلة
  2. يعيد مصفوفة ترابطية من الوظائف المسماة
  3. يسجل Blockstudio نقطة نهاية REST لكل وظيفة
  4. يستدعي عميل 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

تعريف الوظائف

كل مفتاح في المصفوفة المُعادة هو اسم وظيفة. أبسط صيغة هي دالة رد نداء مباشرة:

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 واحدة، وينبغي أن تعيد مصفوفة. تُرسل القيمة المُعادة إلى العميل بصيغة 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];
    }
};

ملاحظات:

  • تُحوّل أسماء الأساليب افتراضيًا إلى أحرف صغيرة مع فصل الكلمات بشرطة سفلية، لذا يصبح getStatus() على هيئة get_status
  • استخدم name: لتجاوز اسم نقطة النهاية صراحةً
  • يطابق Access::Session سلوك 'public' => true القديم
  • يطابق Access::Open سلوك 'public' => 'open' القديم
  • احذف access: للسلوك الافتراضي الذي يتطلب المصادقة فقط

الاستدعاء من JavaScript

يضيف Blockstudio مساعد 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، يُحل الوعد بكائن يحتوي على code وmessage وdata، لذا تحقّق من code:

JavaScript
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');

if (result.code) {
  console.error('RPC failed:', result.message);
}

لا يُرفض الوعد إلا عند فشل الطلب نفسه أو إذا لم تكن الاستجابة JSON.

مع واجهة API التفاعلية

يتكامل RPC طبيعيًا مع واجهة WordPress التفاعلية API. تستدعي إجراءات المخزن وظائف الخادم وتحدّث الحالة التفاعلية بالاستجابة. ويُحدّث 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 التي تحمي فيها نقاط نهاية 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() بيانات اعتماد حديثة من نقطة نهاية POST /wp-json/blockstudio/v1/client/credentials من المصدر نفسه وغير مخزنة مؤقتًا. ولا تُخزّن قيم nonce المنتهية الصلاحية لـ WordPress ورموز CSRF لـ Blockstudio في HTML الصفحة، لذا تواصل الاستدعاءات العامة عملها عندما تعرض ذاكرة التخزين المؤقت الخارجية للصفحات صفحات HTML أقدم من 24 ساعة.

التحديث عند الحاجة: لا يؤدي تحميل صفحة من دون استدعاء API إلى طلب بيانات اعتماد. ويتشارك RPC وعملاء قاعدة البيانات عملية التحديث، ويجددون بيانات الاعتماد بعد خمس دقائق من الاستخدام، ويعيدون المحاولة مرة واحدة عند انتهاء صلاحية nonce أو رمز CSRF. ولا يعاد المحاولة عند فشل الصلاحيات أو حدوث أخطاء في التطبيق. ويظل التحقق من الهوية معتمدًا على ملف تعريف الارتباط لتسجيل دخول الزائر الحالي إلى WordPress؛ فتحديث بيانات الاعتماد لا يمنح إمكانية الوصول إلى الوظائف الخاصة. أبقِ نقطة نهاية بيانات الاعتماد خارج أي ذاكرة تخزين مؤقت لـ CDN أو للوكيل؛ إذ تُعلّم استجاباتها صراحةً بأنها private, no-store.

الوظائف المفتوحة

لخطافات الويب أو استدعاءات API الخارجية التي تحتاج إلى وصول مفتوح تمامًا دون أي رمز:

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

نقطة نهاية REST

في الخلفية، تُربط كل وظيفة بمسار REST:

الكود
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}

نص الطلب: { "params": { ... } }

الاستجابة: القيمة التي تعيدها وظيفة PHP بصيغة JSON.

يمكنك استدعاء نقاط النهاية هذه مباشرةً من أي عميل 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 ينشئ نقاط نهاية CRUD تلقائيًا من مخطط. استخدمه عندما تحتاج إلى عمليات الإنشاء والقراءة والتحديث والحذف القياسية مع التحقق من صحة البيانات.

يُستخدم rpc.php للمنطق المخصص: إرسال رسائل البريد الإلكتروني، واستدعاء واجهات API خارجية، وتجميع البيانات عبر المخططات، وتنفيذ استعلامات معقدة، أو أي مهمة لا تلائم نمط CRUD.

النظامان مستقلان ومتكاملان. تستخدم كتل كثيرة كليهما: db.php لنموذج البيانات وrpc.php لمنطق الأعمال المبني عليه.