概要

新しいRESTルートを登録するには、リクエストがどのように処理されるか、権限チェックがどのように適用されるか、リソースのスキーマがどのように生成されるかなど、エンドポイントの動作を制御するためのコールバック関数をいくつか指定する必要があります。これらのメソッドを通常のPHPファイルで名前空間やクラスでラップせずに宣言することは可能ですが、その方法で宣言されたすべての関数は同じグローバルスコープに共存します。エンドポイントロジックのためにget_items()のような一般的な関数名を使用することに決め、別のプラグイン（または自分のプラグイン内の別のエンドポイント）も同じ名前の関数を登録すると、PHPは致命的なエラーで失敗します。なぜなら、関数get_items()が二重に宣言されているからです。

この問題を回避するには、myplugin_myendpoint_のようなユニークなプレフィックスを使用してコールバック関数に名前を付け、潜在的な競合を避けることができます：

  1. function myplugin_myendpoint_register_routes() { /* ... */ }
  2. function myplugin_myendpoint_get_item() { /* ... */ }
  3. function myplugin_myendpoint_get_item_schema() { /* ... */ }
  4. // etcetera
  6. add_action( 'rest_api_init', 'myplugin_myendpoint_register_routes' );

このアプローチは、テーマfunctions.phpファイル内で一般的に使用されているため、すでにご存知かもしれません。しかし、これらのプレフィックスは不必要に冗長であり、エンドポイントのロジックをより保守可能な方法でグループ化しカプセル化するためのいくつかのより良いオプションが存在します。

WordPressは現在、PHP 5.6以上を必要とします。PHP 5.6は、エンドポイントの機能をカプセル化するための簡単な方法を提供する名前空間をサポートしています。エンドポイントのPHPファイルの先頭でnamespaceを宣言することにより、その名前空間内のすべてのメソッドはその名前空間内で宣言され、グローバル関数と競合しなくなります。これにより、エンドポイントコールバックのために短く、より読みやすい名前を使用できます。

  1. namespace MyPlugin\API\MyEndpoint;
  3. function register_routes() { /* ... */ }
  4. function get_item() { /* ... */ }
  5. function get_item_schema() { /* ... */ }
  6. // and so on
  8. add_action( 'rest_api_init', __NAMESPACE__ . '\\register_routes' );

これらの短い関数名は扱いやすいですが、グローバル関数を宣言することに対して他の利点は提供しません。この理由から、WordPress内のコアREST APIエンドポイントはすべてコントローラークラスを使用して実装されています。

このページの残りの部分では、自分自身のコントローラークラスを書く方法と、その利点について説明します。

コントローラー

コントローラーは入力（WordPress REST APIの場合はWP_REST_Requestオブジェクト）を受け取り、WP_REST_Responseオブジェクトとして応答出力を生成します。例としてコントローラークラスを見てみましょう： 

  1. class My_REST_Posts_Controller {
  3.    // Here initialize our namespace and resource name.
  4.    public function __construct() {
  5.    $this->namespace     = '/my-namespace/v1';
  6.    $this->resource_name = 'posts';
  7.    }
  9.    // Register our routes.
  10.    public function register_routes() {
  11.    register_rest_route( $this->namespace, '/' . $this->resource_name, array(
  12.    // Here we register the readable endpoint for collections.
  13.    array(
  14.    'methods'   => 'GET',
  15.    'callback'  => array( $this, 'get_items' ),
  16.    'permission_callback' => array( $this, 'get_items_permissions_check' ),
  17.    ),
  18.    // Register our schema callback.
  19.    'schema' => array( $this, 'get_item_schema' ),
  20.    ) );
  21.    register_rest_route( $this->namespace, '/' . $this->resource_name . '/(?P<id>[\d]+)', array(
  22.    // Notice how we are registering multiple endpoints the 'schema' equates to an OPTIONS request.
  23.    array(
  24.    'methods'   => 'GET',
  25.    'callback'  => array( $this, 'get_item' ),
  26.    'permission_callback' => array( $this, 'get_item_permissions_check' ),
  27.    ),
  28.    // Register our schema callback.
  29.    'schema' => array( $this, 'get_item_schema' ),
  30.    ) );
  31.    }
  33.    /**
  34.      * Check permissions for the posts.
  35.    *
  36.      * @param WP_REST_Request $request Current request.
  37.    */
  38.    public function get_items_permissions_check( $request ) {
  39.    if ( ! current_user_can( 'read' ) ) {
  40.    return new WP_Error( 'rest_forbidden', esc_html__( 'You cannot view the post resource.' ), array( 'status' => $this->authorization_status_code() ) );
  41.    }
  42.    return true;
  43.    }
  45.    /**
  46.      * Grabs the five most recent posts and outputs them as a rest response.
  47.    *
  48.      * @param WP_REST_Request $request Current request.
  49.    */
  50.    public function get_items( $request ) {
  51.    $args = array(
  52.    'post_per_page' => 5,
  53.    );
  54.    $posts = get_posts( $args );
  56.    $data = array();
  58.    if ( empty( $posts ) ) {
  59.    return rest_ensure_response( $data );
  60.    }
  62.    foreach ( $posts as $post ) {
  63.    $response = $this->prepare_item_for_response( $post, $request );
  64.    $data[] = $this->prepare_response_for_collection( $response );
  65.    }
  67.    // Return all of our comment response data.
  68.    return rest_ensure_response( $data );
  69.    }
  71.    /**
  72.      * Check permissions for the posts.
  73.    *
  74.      * @param WP_REST_Request $request Current request.
  75.    */
  76.    public function get_item_permissions_check( $request ) {
  77.    if ( ! current_user_can( 'read' ) ) {
  78.    return new WP_Error( 'rest_forbidden', esc_html__( 'You cannot view the post resource.' ), array( 'status' => $this->authorization_status_code() ) );
  79.    }
  80.    return true;
  81.    }
  83.    /**
  84.      * Gets post data of requested post id and outputs it as a rest response.
  85.    *
  86.      * @param WP_REST_Request $request Current request.
  87.    */
  88.    public function get_item( $request ) {
  89.    $id = (int) $request['id'];
  90.    $post = get_post( $id );
  92.    if ( empty( $post ) ) {
  93.    return rest_ensure_response( array() );
  94.    }
  96.    $response = $this->prepare_item_for_response( $post, $request );
  98.    // Return all of our post response data.
  99.    return $response;
  100.    }
  102.    /**
  103.      * Matches the post data to the schema we want.
  104.    *
  105.      * @param WP_Post $post The comment object whose response is being prepared.
  106.    */
  107.    public function prepare_item_for_response( $post, $request ) {
  108.    $post_data = array();
  110.    $schema = $this->get_item_schema( $request );
  112.    // We are also renaming the fields to more understandable names.
  113.    if ( isset( $schema['properties']['id'] ) ) {
  114.    $post_data['id'] = (int) $post->ID;
  115.    }
  117.    if ( isset( $schema['properties']['content'] ) ) {
  118.    $post_data['content'] = apply_filters( 'the_content', $post->post_content, $post );
  119.    }
  121.    return rest_ensure_response( $post_data );
  122.    }
  124.    /**
  125.      * Prepare a response for inserting into a collection of responses.
  126.    *
  127.      * This is copied from WP_REST_Controller class in the WP REST API v2 plugin.
  128.    *
  129.      * @param WP_REST_Response $response Response object.
  130.      * @return array Response data, ready for insertion into collection data.
  131.    */
  132.    public function prepare_response_for_collection( $response ) {
  133.    if ( ! ( $response instanceof WP_REST_Response ) ) {
  134.    return $response;
  135.    }
  137.    $data = (array) $response->get_data();
  138.    $server = rest_get_server();
  140.    if ( method_exists( $server, 'get_compact_response_links' ) ) {
  141.    $links = call_user_func( array( $server, 'get_compact_response_links' ), $response );
  142.    } else {
  143.    $links = call_user_func( array( $server, 'get_response_links' ), $response );
  144.    }
  146.    if ( ! empty( $links ) ) {
  147.    $data['_links'] = $links;
  148.    }
  150.    return $data;
  151.    }
  153.    /**
  154.      * Get our sample schema for a post.
  155.    *
  156.      * @return array The sample schema for a post
  157.    */
  158.    public function get_item_schema() {
  159.    if ( $this->schema ) {
  160.    // Since WordPress 5.3, the schema can be cached in the $schema property.
  161.    return $this->schema;
  162.    }
  164.    $this->schema = array(
  165.    // This tells the spec of JSON Schema we are using which is draft 4.
  166.    '$schema'              => 'http://json-schema.org/draft-04/schema#',
  167.    // The title property marks the identity of the resource.
  168.    'title'                => 'post',
  169.    'type'                 => 'object',
  170.    // In JSON Schema you can specify object properties in the properties attribute.
  171.    'properties'           => array(
  172.    'id' => array(
  173.    'description'  => esc_html__( 'Unique identifier for the object.', 'my-textdomain' ),
  174.    'type'         => 'integer',
  175.    'context'      => array( 'view', 'edit', 'embed' ),
  176.    'readonly'     => true,
  177.    ),
  178.    'content' => array(
  179.    'description'  => esc_html__( 'The content for the object.', 'my-textdomain' ),
  180.    'type'         => 'string',
  181.    ),
  182.    ),
  183.    );
  185.    return $this->schema;
  186.    }
  188.    // Sets up the proper HTTP status code for authorization.
  189.    public function authorization_status_code() {
  191.    $status = 401;
  193.    if ( is_user_logged_in() ) {
  194.    $status = 403;
  195.    }
  197.    return $status;
  198.    }
  199. }
  201. // Function to register our new routes from the controller.
  202. function prefix_register_my_rest_routes() {
  203.    $controller = new My_REST_Posts_Controller();
  204.    $controller->register_routes();
  205. }
  207. add_action( 'rest_api_init', 'prefix_register_my_rest_routes' );

クラスの利点

このクラスには、単純な関数を使用して書いたかもしれないすべての同じコンポーネントが含まれています。クラスの構造は、$this->method_name()構文を使用して関連するメソッドを参照する便利な方法を提供しますが、名前空間とは異なり、クラスは値をキャッシュし、ロジックを共有することも許可します。

get_item_schemaメソッドでは、生成されたスキーマを$this->schemaとしてクラスに保存することに注意してください。クラスプロパティは、この種の生成された値をキャッシュするのを容易にします。WordPress 5.3でのスキーマキャッシングの導入により、いくつかのコアREST APIコレクション応答の速度が最大40%向上したため、自分のコントローラーでもこのパターンに従うことを検討すべきです。

クラスの継承 & WP_REST_Controller

上記で、クラスがグローバル関数のカプセル化の問題をどのように解決するか、クラスインスタンスが複雑な値をキャッシュして応答処理を高速化する方法を見てきました。クラスのもう一つの大きな利点は、クラスの継承が複数のエンドポイント間でロジックを共有できる方法です。

ここでの例のクラスは、基底クラスを拡張していませんが、WordPressコア内のすべてのエンドポイントコントローラーは、abstractコントローラークラスであるWP_REST_Controllerを拡張します。このクラスを拡張することで、次のような便利なメソッドにアクセスできますが、これに限定されません：

get_item、register_routes、update_item_permissions_checkのようなエンドポイント固有のメソッドは、抽象クラスによって完全には実装されておらず、自分のクラスで定義する必要があります。

このコントローラーのメソッドの完全なリストについては、WP_REST_Controllerクラスリファレンスページを訪れてください。

重要な点は、WP_REST_Controllerがabstractクラスとして実装されており、複数のクラスで明確に必要なロジックのみを含んでいることです。継承は、拡張する基底クラスにクラスを結びつけ、考慮が不十分な継承ツリーはエンドポイントの保守を非常に困難にする可能性があります。

例えば、投稿エンドポイントのためのコントローラークラスを作成し（上記の例のように）、カスタム投稿タイプもサポートしたい場合、My_REST_Posts_Controllerをこのように拡張してはいけません：class My_CPT_REST_Controller extends My_REST_Posts_Controller。代わりに、共有ロジックのためにまったく別の基底コントローラークラスを作成するか、My_REST_Posts_Controllerがすべての利用可能な投稿タイプを処理するようにするべきです。エンドポイントロジックはビジネス要件の変更の影響を受けるため、基底投稿コントローラーを更新するたびに無関係な複数のコントローラーを変更する必要がないようにしたいです。

ほとんどの場合、各エンドポイントコントローラーが実装または拡張できるinterfaceまたはabstract classとして基底コントローラークラスを作成するか、コアのWordPress RESTクラスのいずれかを直接拡張することをお勧めします。

内部WordPress REST APIクラス

WordPress REST APIは、その内部クラスのために意図的なデザインパターンに従い、インフラストラクチャまたはエンドポイントクラスとして分類できます。

エンドポイントクラスは、WordPressリソースに対してCRUD操作を実行するために必要な機能的ロジックをカプセル化します。WordPressは多くのREST APIエンドポイント（WP_REST_Posts_Controllerなど）を公開していますが、上記で説明したように、すべてのエンドポイントは共通の基底コントローラークラスから拡張されます：

  • WP_REST_Controller：すべてのWordPressコアエンドポイントの基底クラス。このクラスは、WordPressリソースを操作するための一貫したパターンを表すように設計されています。WP_REST_Controllerを実装するエンドポイントと対話する際、HTTPクライアントは各エンドポイントが一貫した方法で動作することを期待できます。

インフラストラクチャクラスは、エンドポイントクラスをサポートします。データ変換を行うことなく、WordPress REST APIのロジックを処理します。WordPress REST APIは、3つの主要なインフラストラクチャクラスを実装しています：

  • WP_REST_Server：WordPress REST APIの主要なコントローラー。ルートはWordPress内でサーバーに登録されます。WP_REST_Serverがリクエストを処理するために呼び出されると、どのルートが呼び出されるかを決定し、ルートコールバックにWP_REST_Requestオブジェクトを渡します。WP_REST_Serverは認証も処理し、リクエストの検証や権限チェックを行うことができます。
  • WP_REST_Request：リクエストの性質を表すオブジェクト。このオブジェクトには、リクエストヘッダー、パラメータ、メソッド、ルートなどのリクエストの詳細が含まれています。また、リクエストの検証やサニタイズも行うことができます。
  • WP_REST_Response：応答の性質を表すオブジェクト。このクラスはWP_HTTP_Responseを拡張し、ヘッダー、ボディ、ステータスを含み、リンクメディアを追加するためのadd_link()や、クエリナビゲーションヘッダーを取得するためのquery_navigation_headers()のようなヘルパーメソッドを提供します。

API駆動型アプリケーションのほとんどのタイプでは、インフラストラクチャ層を直接拡張または操作する必要はありませんが、自分自身のREST APIエンドポイントを実装している場合、アプリケーションはWP_REST_Controllerを拡張する1つ以上のエンドポイントコントローラークラスから利益を得る可能性があります。