본문으로 건너뛰기

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는 RPC 함수가 포함된 블록이 있는 페이지에 bs.fn() 헬퍼를 자동으로 삽입합니다.

시그니처: bs.fn(functionName, params?, blockName?) -> Promise

블록 이름 전달하기

bs.fn()은 세 번째 인수를 생략하면 document.currentScript의 data-block 속성으로 대체됩니다. 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()는 HTTP 상태와 관계없이 파싱된 JSON 본문으로 완료됩니다. 함수가 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);
}

요청 자체가 실패하거나 응답이 JSON가 아닌 경우에만 Promise가 거부됩니다.

Interactivity API와 함께 사용하기

RPC는 WordPress Interactivity 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 엔드포인트에서 새 인증 정보를 가져옵니다. 만료되는 WordPress nonce와 Blockstudio CSRF 토큰은 페이지 HTML에 저장되지 않으므로, 외부 페이지 캐시가 24시간이 지난 HTML를 제공해도 공개 호출은 계속 작동합니다.

갱신은 지연 실행됩니다. API를 호출하지 않고 페이지를 로드하면 인증 정보를 요청하지 않습니다. RPC와 데이터베이스 클라이언트는 갱신 요청을 공유하고, 5분간 사용한 후 인증 정보를 갱신하며, 만료된 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 클라이언트에서든 직접 호출할 수 있지만, nonce 인증을 자동으로 처리하므로 bs.fn()를 사용하는 것이 좋습니다.

훅

액션은 REST와 PHP에서 호출되는 RPC 호출 전후에 실행됩니다. 모든 훅은 단일 $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는 그 위에 구현되는 비즈니스 로직에 사용합니다.