<?php

[0] Fix | Delete

/**

[1] Fix | Delete

* REST API: WP_REST_Search_Controller class

[2] Fix | Delete

*

[3] Fix | Delete

* @package WordPress

[4] Fix | Delete

* @subpackage REST_API

[5] Fix | Delete

* @since 5.0.0

[6] Fix | Delete

*/

[7] Fix | Delete

[8] Fix | Delete

/**

[9] Fix | Delete

* Core class to search through all WordPress content via the REST API.

[10] Fix | Delete

*

[11] Fix | Delete

* @since 5.0.0

[12] Fix | Delete

*

[13] Fix | Delete

* @see WP_REST_Controller

[14] Fix | Delete

*/

[15] Fix | Delete

class WP_REST_Search_Controller extends WP_REST_Controller {

[16] Fix | Delete

[17] Fix | Delete

/**

[18] Fix | Delete

* ID property name.

[19] Fix | Delete

*/

[20] Fix | Delete

const PROP_ID = 'id';

[21] Fix | Delete

[22] Fix | Delete

/**

[23] Fix | Delete

* Title property name.

[24] Fix | Delete

*/

[25] Fix | Delete

const PROP_TITLE = 'title';

[26] Fix | Delete

[27] Fix | Delete

/**

[28] Fix | Delete

* URL property name.

[29] Fix | Delete

*/

[30] Fix | Delete

const PROP_URL = 'url';

[31] Fix | Delete

[32] Fix | Delete

/**

[33] Fix | Delete

* Type property name.

[34] Fix | Delete

*/

[35] Fix | Delete

const PROP_TYPE = 'type';

[36] Fix | Delete

[37] Fix | Delete

/**

[38] Fix | Delete

* Subtype property name.

[39] Fix | Delete

*/

[40] Fix | Delete

const PROP_SUBTYPE = 'subtype';

[41] Fix | Delete

[42] Fix | Delete

/**

[43] Fix | Delete

* Identifier for the 'any' type.

[44] Fix | Delete

*/

[45] Fix | Delete

const TYPE_ANY = 'any';

[46] Fix | Delete

[47] Fix | Delete

/**

[48] Fix | Delete

* Search handlers used by the controller.

[49] Fix | Delete

*

[50] Fix | Delete

* @since 5.0.0

[51] Fix | Delete

* @var WP_REST_Search_Handler[]

[52] Fix | Delete

*/

[53] Fix | Delete

protected $search_handlers = array();

[54] Fix | Delete

[55] Fix | Delete

/**

[56] Fix | Delete

* Constructor.

[57] Fix | Delete

*

[58] Fix | Delete

* @since 5.0.0

[59] Fix | Delete

*

[60] Fix | Delete

* @param array $search_handlers List of search handlers to use in the controller. Each search

[61] Fix | Delete

* handler instance must extend the `WP_REST_Search_Handler` class.

[62] Fix | Delete

*/

[63] Fix | Delete

public function __construct( array $search_handlers ) {

[64] Fix | Delete

$this->namespace = 'wp/v2';

[65] Fix | Delete

$this->rest_base = 'search';

[66] Fix | Delete

[67] Fix | Delete

foreach ( $search_handlers as $search_handler ) {

[68] Fix | Delete

if ( ! $search_handler instanceof WP_REST_Search_Handler ) {

[69] Fix | Delete

_doing_it_wrong(

[70] Fix | Delete

__METHOD__,

[71] Fix | Delete

/* translators: %s: PHP class name. */

[72] Fix | Delete

sprintf( __( 'REST search handlers must extend the %s class.' ), 'WP_REST_Search_Handler' ),

[73] Fix | Delete

'5.0.0'

[74] Fix | Delete

);

[75] Fix | Delete

continue;

[76] Fix | Delete

}

[77] Fix | Delete

[78] Fix | Delete

$this->search_handlers[ $search_handler->get_type() ] = $search_handler;

[79] Fix | Delete

}

[80] Fix | Delete

}

[81] Fix | Delete

[82] Fix | Delete

/**

[83] Fix | Delete

* Registers the routes for the search controller.

[84] Fix | Delete

*

[85] Fix | Delete

* @since 5.0.0

[86] Fix | Delete

*

[87] Fix | Delete

* @see register_rest_route()

[88] Fix | Delete

*/

[89] Fix | Delete

public function register_routes() {

[90] Fix | Delete

register_rest_route(

[91] Fix | Delete

$this->namespace,

[92] Fix | Delete

'/' . $this->rest_base,

[93] Fix | Delete

array(

[94] Fix | Delete

array(

[95] Fix | Delete

'methods' => WP_REST_Server::READABLE,

[96] Fix | Delete

'callback' => array( $this, 'get_items' ),

[97] Fix | Delete

'permission_callback' => array( $this, 'get_items_permission_check' ),

[98] Fix | Delete

'args' => $this->get_collection_params(),

[99] Fix | Delete

),

[100] Fix | Delete

'schema' => array( $this, 'get_public_item_schema' ),

[101] Fix | Delete

)

[102] Fix | Delete

);

[103] Fix | Delete

}

[104] Fix | Delete

[105] Fix | Delete

/**

[106] Fix | Delete

* Checks if a given request has access to search content.

[107] Fix | Delete

*

[108] Fix | Delete

* @since 5.0.0

[109] Fix | Delete

*

[110] Fix | Delete

* @param WP_REST_Request $request Full details about the request.

[111] Fix | Delete

* @return true|WP_Error True if the request has search access, WP_Error object otherwise.

[112] Fix | Delete

*/

[113] Fix | Delete

public function get_items_permission_check( $request ) {

[114] Fix | Delete

return true;

[115] Fix | Delete

}

[116] Fix | Delete

[117] Fix | Delete

/**

[118] Fix | Delete

* Retrieves a collection of search results.

[119] Fix | Delete

*

[120] Fix | Delete

* @since 5.0.0

[121] Fix | Delete

*

[122] Fix | Delete

* @param WP_REST_Request $request Full details about the request.

[123] Fix | Delete

* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.

[124] Fix | Delete

*/

[125] Fix | Delete

public function get_items( $request ) {

[126] Fix | Delete

$handler = $this->get_search_handler( $request );

[127] Fix | Delete

if ( is_wp_error( $handler ) ) {

[128] Fix | Delete

return $handler;

[129] Fix | Delete

}

[130] Fix | Delete

[131] Fix | Delete

$result = $handler->search_items( $request );

[132] Fix | Delete

[133] Fix | Delete

if ( ! isset( $result[ WP_REST_Search_Handler::RESULT_IDS ] ) || ! is_array( $result[ WP_REST_Search_Handler::RESULT_IDS ] ) || ! isset( $result[ WP_REST_Search_Handler::RESULT_TOTAL ] ) ) {

[134] Fix | Delete

return new WP_Error(

[135] Fix | Delete

'rest_search_handler_error',

[136] Fix | Delete

__( 'Internal search handler error.' ),

[137] Fix | Delete

array( 'status' => 500 )

[138] Fix | Delete

);

[139] Fix | Delete

}

[140] Fix | Delete

[141] Fix | Delete

$ids = $result[ WP_REST_Search_Handler::RESULT_IDS ];

[142] Fix | Delete

[143] Fix | Delete

$results = array();

[144] Fix | Delete

[145] Fix | Delete

foreach ( $ids as $id ) {

[146] Fix | Delete

$data = $this->prepare_item_for_response( $id, $request );

[147] Fix | Delete

$results[] = $this->prepare_response_for_collection( $data );

[148] Fix | Delete

}

[149] Fix | Delete

[150] Fix | Delete

$total = (int) $result[ WP_REST_Search_Handler::RESULT_TOTAL ];

[151] Fix | Delete

$page = (int) $request['page'];

[152] Fix | Delete

$per_page = (int) $request['per_page'];

[153] Fix | Delete

$max_pages = (int) ceil( $total / $per_page );

[154] Fix | Delete

[155] Fix | Delete

if ( $page > $max_pages && $total > 0 ) {

[156] Fix | Delete

return new WP_Error(

[157] Fix | Delete

'rest_search_invalid_page_number',

[158] Fix | Delete

__( 'The page number requested is larger than the number of pages available.' ),

[159] Fix | Delete

array( 'status' => 400 )

[160] Fix | Delete

);

[161] Fix | Delete

}

[162] Fix | Delete

[163] Fix | Delete

$response = rest_ensure_response( $results );

[164] Fix | Delete

$response->header( 'X-WP-Total', $total );

[165] Fix | Delete

$response->header( 'X-WP-TotalPages', $max_pages );

[166] Fix | Delete

[167] Fix | Delete

$request_params = $request->get_query_params();

[168] Fix | Delete

$base = add_query_arg( urlencode_deep( $request_params ), rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) ) );

[169] Fix | Delete

[170] Fix | Delete

if ( $page > 1 ) {

[171] Fix | Delete

$prev_link = add_query_arg( 'page', $page - 1, $base );

[172] Fix | Delete

$response->link_header( 'prev', $prev_link );

[173] Fix | Delete

}

[174] Fix | Delete

if ( $page < $max_pages ) {

[175] Fix | Delete

$next_link = add_query_arg( 'page', $page + 1, $base );

[176] Fix | Delete

$response->link_header( 'next', $next_link );

[177] Fix | Delete

}

[178] Fix | Delete

[179] Fix | Delete

return $response;

[180] Fix | Delete

}

[181] Fix | Delete

[182] Fix | Delete

/**

[183] Fix | Delete

* Prepares a single search result for response.

[184] Fix | Delete

*

[185] Fix | Delete

* @since 5.0.0

[186] Fix | Delete

* @since 5.6.0 The `$id` parameter can accept a string.

[187] Fix | Delete

* @since 5.9.0 Renamed `$id` to `$item` to match parent class for PHP 8 named parameter support.

[188] Fix | Delete

*

[189] Fix | Delete

* @param int|string $item ID of the item to prepare.

[190] Fix | Delete

* @param WP_REST_Request $request Request object.

[191] Fix | Delete

* @return WP_REST_Response Response object.

[192] Fix | Delete

*/

[193] Fix | Delete

public function prepare_item_for_response( $item, $request ) {

[194] Fix | Delete

// Restores the more descriptive, specific name for use within this method.

[195] Fix | Delete

$item_id = $item;

[196] Fix | Delete

[197] Fix | Delete

$handler = $this->get_search_handler( $request );

[198] Fix | Delete

if ( is_wp_error( $handler ) ) {

[199] Fix | Delete

return new WP_REST_Response();

[200] Fix | Delete

}

[201] Fix | Delete

[202] Fix | Delete

$fields = $this->get_fields_for_response( $request );

[203] Fix | Delete

[204] Fix | Delete

$data = $handler->prepare_item( $item_id, $fields );

[205] Fix | Delete

$data = $this->add_additional_fields_to_object( $data, $request );

[206] Fix | Delete

[207] Fix | Delete

$context = ! empty( $request['context'] ) ? $request['context'] : 'view';

[208] Fix | Delete

$data = $this->filter_response_by_context( $data, $context );

[209] Fix | Delete

[210] Fix | Delete

$response = rest_ensure_response( $data );

[211] Fix | Delete

[212] Fix | Delete

if ( rest_is_field_included( '_links', $fields ) || rest_is_field_included( '_embedded', $fields ) ) {

[213] Fix | Delete

$links = $handler->prepare_item_links( $item_id );

[214] Fix | Delete

$links['collection'] = array(

[215] Fix | Delete

'href' => rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) ),

[216] Fix | Delete

);

[217] Fix | Delete

$response->add_links( $links );

[218] Fix | Delete

}

[219] Fix | Delete

[220] Fix | Delete

return $response;

[221] Fix | Delete

}

[222] Fix | Delete

[223] Fix | Delete

/**

[224] Fix | Delete

* Retrieves the item schema, conforming to JSON Schema.

[225] Fix | Delete

*

[226] Fix | Delete

* @since 5.0.0

[227] Fix | Delete

*

[228] Fix | Delete

* @return array Item schema data.

[229] Fix | Delete

*/

[230] Fix | Delete

public function get_item_schema() {

[231] Fix | Delete

if ( $this->schema ) {

[232] Fix | Delete

return $this->add_additional_fields_schema( $this->schema );

[233] Fix | Delete

}

[234] Fix | Delete

[235] Fix | Delete

$types = array();

[236] Fix | Delete

$subtypes = array();

[237] Fix | Delete

[238] Fix | Delete

foreach ( $this->search_handlers as $search_handler ) {

[239] Fix | Delete

$types[] = $search_handler->get_type();

[240] Fix | Delete

$subtypes = array_merge( $subtypes, $search_handler->get_subtypes() );

[241] Fix | Delete

}

[242] Fix | Delete

[243] Fix | Delete

$types = array_unique( $types );

[244] Fix | Delete

$subtypes = array_unique( $subtypes );

[245] Fix | Delete

[246] Fix | Delete

$schema = array(

[247] Fix | Delete

'$schema' => 'http://json-schema.org/draft-04/schema#',

[248] Fix | Delete

'title' => 'search-result',

[249] Fix | Delete

'type' => 'object',

[250] Fix | Delete

'properties' => array(

[251] Fix | Delete

self::PROP_ID => array(

[252] Fix | Delete

'description' => __( 'Unique identifier for the object.' ),

[253] Fix | Delete

'type' => array( 'integer', 'string' ),

[254] Fix | Delete

'context' => array( 'view', 'embed' ),

[255] Fix | Delete

'readonly' => true,

[256] Fix | Delete

),

[257] Fix | Delete

self::PROP_TITLE => array(

[258] Fix | Delete

'description' => __( 'The title for the object.' ),

[259] Fix | Delete

'type' => 'string',

[260] Fix | Delete

'context' => array( 'view', 'embed' ),

[261] Fix | Delete

'readonly' => true,

[262] Fix | Delete

),

[263] Fix | Delete

self::PROP_URL => array(

[264] Fix | Delete

'description' => __( 'URL to the object.' ),

[265] Fix | Delete

'type' => 'string',

[266] Fix | Delete

'format' => 'uri',

[267] Fix | Delete

'context' => array( 'view', 'embed' ),

[268] Fix | Delete

'readonly' => true,

[269] Fix | Delete

),

[270] Fix | Delete

self::PROP_TYPE => array(

[271] Fix | Delete

'description' => __( 'Object type.' ),

[272] Fix | Delete

'type' => 'string',

[273] Fix | Delete

'enum' => $types,

[274] Fix | Delete

'context' => array( 'view', 'embed' ),

[275] Fix | Delete

'readonly' => true,

[276] Fix | Delete

),

[277] Fix | Delete

self::PROP_SUBTYPE => array(

[278] Fix | Delete

'description' => __( 'Object subtype.' ),

[279] Fix | Delete

'type' => 'string',

[280] Fix | Delete

'enum' => $subtypes,

[281] Fix | Delete

'context' => array( 'view', 'embed' ),

[282] Fix | Delete

'readonly' => true,

[283] Fix | Delete

),

[284] Fix | Delete

),

[285] Fix | Delete

);

[286] Fix | Delete

[287] Fix | Delete

$this->schema = $schema;

[288] Fix | Delete

[289] Fix | Delete

return $this->add_additional_fields_schema( $this->schema );

[290] Fix | Delete

}

[291] Fix | Delete

[292] Fix | Delete

/**

[293] Fix | Delete

* Retrieves the query params for the search results collection.

[294] Fix | Delete

*

[295] Fix | Delete

* @since 5.0.0

[296] Fix | Delete

*

[297] Fix | Delete

* @return array Collection parameters.

[298] Fix | Delete

*/

[299] Fix | Delete

public function get_collection_params() {

[300] Fix | Delete

$types = array();

[301] Fix | Delete

$subtypes = array();

[302] Fix | Delete

[303] Fix | Delete

foreach ( $this->search_handlers as $search_handler ) {

[304] Fix | Delete

$types[] = $search_handler->get_type();

[305] Fix | Delete

$subtypes = array_merge( $subtypes, $search_handler->get_subtypes() );

[306] Fix | Delete

}

[307] Fix | Delete

[308] Fix | Delete

$types = array_unique( $types );

[309] Fix | Delete

$subtypes = array_unique( $subtypes );

[310] Fix | Delete

[311] Fix | Delete

$query_params = parent::get_collection_params();

[312] Fix | Delete

[313] Fix | Delete

$query_params['context']['default'] = 'view';

[314] Fix | Delete

[315] Fix | Delete

$query_params[ self::PROP_TYPE ] = array(

[316] Fix | Delete

'default' => $types[0],

[317] Fix | Delete

'description' => __( 'Limit results to items of an object type.' ),

[318] Fix | Delete

'type' => 'string',

[319] Fix | Delete

'enum' => $types,

[320] Fix | Delete

);

[321] Fix | Delete

[322] Fix | Delete

$query_params[ self::PROP_SUBTYPE ] = array(

[323] Fix | Delete

'default' => self::TYPE_ANY,

[324] Fix | Delete

'description' => __( 'Limit results to items of one or more object subtypes.' ),

[325] Fix | Delete

'type' => 'array',

[326] Fix | Delete

'items' => array(

[327] Fix | Delete

'enum' => array_merge( $subtypes, array( self::TYPE_ANY ) ),

[328] Fix | Delete

'type' => 'string',

[329] Fix | Delete

),

[330] Fix | Delete

'sanitize_callback' => array( $this, 'sanitize_subtypes' ),

[331] Fix | Delete

);

[332] Fix | Delete

[333] Fix | Delete

$query_params['exclude'] = array(

[334] Fix | Delete

'description' => __( 'Ensure result set excludes specific IDs.' ),

[335] Fix | Delete

'type' => 'array',

[336] Fix | Delete

'items' => array(

[337] Fix | Delete

'type' => 'integer',

[338] Fix | Delete

),

[339] Fix | Delete

'default' => array(),

[340] Fix | Delete

);

[341] Fix | Delete

[342] Fix | Delete

$query_params['include'] = array(

[343] Fix | Delete

'description' => __( 'Limit result set to specific IDs.' ),

[344] Fix | Delete

'type' => 'array',

[345] Fix | Delete

'items' => array(

[346] Fix | Delete

'type' => 'integer',

[347] Fix | Delete

),

[348] Fix | Delete

'default' => array(),

[349] Fix | Delete

);

[350] Fix | Delete

[351] Fix | Delete

return $query_params;

[352] Fix | Delete

}

[353] Fix | Delete

[354] Fix | Delete

/**

[355] Fix | Delete

* Sanitizes the list of subtypes, to ensure only subtypes of the passed type are included.

[356] Fix | Delete

*

[357] Fix | Delete

* @since 5.0.0

[358] Fix | Delete

*

[359] Fix | Delete

* @param string|array $subtypes One or more subtypes.

[360] Fix | Delete

* @param WP_REST_Request $request Full details about the request.

[361] Fix | Delete

* @param string $parameter Parameter name.

[362] Fix | Delete

* @return string[]|WP_Error List of valid subtypes, or WP_Error object on failure.

[363] Fix | Delete

*/

[364] Fix | Delete

public function sanitize_subtypes( $subtypes, $request, $parameter ) {

[365] Fix | Delete

$subtypes = wp_parse_slug_list( $subtypes );

[366] Fix | Delete

[367] Fix | Delete

$subtypes = rest_parse_request_arg( $subtypes, $request, $parameter );

[368] Fix | Delete

if ( is_wp_error( $subtypes ) ) {

[369] Fix | Delete

return $subtypes;

[370] Fix | Delete

}

[371] Fix | Delete

[372] Fix | Delete

// 'any' overrides any other subtype.

[373] Fix | Delete

if ( in_array( self::TYPE_ANY, $subtypes, true ) ) {

[374] Fix | Delete

return array( self::TYPE_ANY );

[375] Fix | Delete

}

[376] Fix | Delete

[377] Fix | Delete

$handler = $this->get_search_handler( $request );

[378] Fix | Delete

if ( is_wp_error( $handler ) ) {

[379] Fix | Delete

return $handler;

[380] Fix | Delete

}

[381] Fix | Delete

[382] Fix | Delete

return array_intersect( $subtypes, $handler->get_subtypes() );

[383] Fix | Delete

}

[384] Fix | Delete

[385] Fix | Delete

/**

[386] Fix | Delete

* Gets the search handler to handle the current request.

[387] Fix | Delete

*

[388] Fix | Delete

* @since 5.0.0

[389] Fix | Delete

*

[390] Fix | Delete

* @param WP_REST_Request $request Full details about the request.

[391] Fix | Delete

* @return WP_REST_Search_Handler|WP_Error Search handler for the request type, or WP_Error object on failure.

[392] Fix | Delete

*/

[393] Fix | Delete

protected function get_search_handler( $request ) {

[394] Fix | Delete

$type = $request->get_param( self::PROP_TYPE );

[395] Fix | Delete

[396] Fix | Delete

if ( ! $type || ! is_string( $type ) || ! isset( $this->search_handlers[ $type ] ) ) {

[397] Fix | Delete

return new WP_Error(

[398] Fix | Delete

'rest_search_invalid_type',

[399] Fix | Delete

__( 'Invalid type parameter.' ),

[400] Fix | Delete

array( 'status' => 400 )

[401] Fix | Delete

);

[402] Fix | Delete

}

[403] Fix | Delete

[404] Fix | Delete

return $this->search_handlers[ $type ];

[405] Fix | Delete

}

[406] Fix | Delete

}

[407] Fix | Delete

[408] Fix | Delete