概要

エンドポイントを書く際には、エンドポイントの機能を処理するためにコントローラークラスを使用することが役立ちます。コントローラークラスは、APIと対話するための標準的な方法を提供し、APIとの対話をより保守可能な方法にします。WordPressの現在の最小PHPバージョンは5.2であり、WordPressエコシステム全体で使用されるエンドポイントを開発する場合は、WordPressの最小要件をサポートすることを検討すべきです。

PHP 5.2には名前空間が組み込まれていません。これは、宣言したすべての関数がグローバルスコープに存在することを意味します。get_items()のようなエンドポイントのために一般的な関数名を使用することに決め、別のプラグインもその関数を登録した場合、PHPは致命的なエラーで失敗します。これは、関数get_items()が二重に宣言されているためです。エンドポイントをラップすることで、これらの名前の衝突を回避し、APIと対話するための一貫した方法を持つことができます。

コントローラー

コントローラーは通常、1つのことを行います。入力を受け取り、出力を生成します。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.      * Grabs the five most recent posts and outputs them 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 = prepare_item_for_response( $post );
  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.      * @param WP_REST_Request $request Current request.
  157.      */
  158.     public function get_item_schema( $request ) {
  159.         $schema = array(
  160.             // This tells the spec of JSON Schema we are using which is draft 4.
  161.             '$schema'              => 'http://json-schema.org/draft-04/schema#',
  162.             // The title property marks the identity of the resource.
  163.             'title'                => 'post',
  164.             'type'                 => 'object',
  165.             // In JSON Schema you can specify object properties in the properties attribute.
  166.             'properties'           => array(
  167.             'id' => array(
  168.             'description'  => esc_html__( 'Unique identifier for the object.', 'my-textdomain' ),
  169.             'type'         => 'integer',
  170.             'context'      => array( 'view', 'edit', 'embed' ),
  171.             'readonly'     => true,
  172.             ),
  173.             'content' => array(
  174.             'description'  => esc_html__( 'The content for the object.', 'my-textdomain' ),
  175.             'type'         => 'string',
  176.             ),
  177.             ),
  178.         );
  180.         return $schema;
  181.     }
  183.     // Sets up the proper HTTP status code for authorization.
  184.     public function authorization_status_code() {
  186.         $status = 401;
  188.         if ( is_user_logged_in() ) {
  189.             $status = 403;
  190.         }
  192.         return $status;
  193.     }
  194. }
  196. // Function to register our new routes from the controller.
  197. function prefix_register_my_rest_routes() {
  198.     $controller = new My_REST_Posts_Controller();
  199.     $controller->register_routes();
  200. }
  202. add_action( 'rest_api_init', 'prefix_register_my_rest_routes' );

概要と未来

コントローラークラスは、エンドポイントを開発する際に2つの大きな問題に対処します。名前空間の欠如と一貫した構造です。エンドポイントの継承を乱用しないことが重要です。例えば、上記の例のように投稿エンドポイントのためにコントローラークラスを書き、カスタム投稿タイプもサポートしたい場合、My_REST_Posts_Controllerをこのようにclass My_CPT_REST_Controller extends My_REST_Posts_Controllerのように拡張してはいけません。

代わりに、まったく別のコントローラークラスを作成するか、My_REST_Posts_Controllerがすべての利用可能な投稿タイプを処理するようにするべきです。継承の暗い深淵に進むときは、親クラスがいつでも変更される可能性があり、サブクラスがそれに依存している場合、大きな頭痛の種になることを理解することが重要です。ほとんどの場合、interfaceまたはabstract classとしてベースコントローラークラスを作成し、各エンドポイントコントローラーが実装または拡張できるようにしたいでしょう。abstract classアプローチは、WP_REST_Controllerクラスのコアへの潜在的な統合のためにWP REST APIチームによって採用されています。

現在、投稿、投稿タイプ、投稿ステータス、リビジョン、タクソノミー、用語、ユーザー、コメント、および添付ファイル/メディアリソースをサポートする「コアエンドポイント」が、最終的にWordPressコアに移行されることを期待している機能プラグインで開発されています。このプラグイン内には、エンドポイント用の独自のコントローラーを構築するために使用できる提案されたWP_REST_Controllerクラスがあります。WP_REST_Controllerは、多くの利点とAPIのためのエンドポイントを作成するための一貫した方法を特徴としています。