1<?php
  2/**
  3 * REST API: WP_REST_Search_Handler class
  4 *
  5 * @package WordPress
  6 * @subpackage REST_API
  7 * @since 5.0.0
  8 */
  9
 10/**
 11 * Core base class representing a search handler for an object type in the REST API.
 12 *
 13 * @since 5.0.0
 14 */
 15#[AllowDynamicProperties]
 16abstract class WP_REST_Search_Handler {
 17
 18	/**
 19	 * Field containing the IDs in the search result.
 20	 */
 21	const RESULT_IDS = 'ids';
 22
 23	/**
 24	 * Field containing the total count in the search result.
 25	 */
 26	const RESULT_TOTAL = 'total';
 27
 28	/**
 29	 * Object type managed by this search handler.
 30	 *
 31	 * @since 5.0.0
 32	 * @var string
 33	 */
 34	protected $type = '';
 35
 36	/**
 37	 * Object subtypes managed by this search handler.
 38	 *
 39	 * @since 5.0.0
 40	 * @var string[]
 41	 */
 42	protected $subtypes = array();
 43
 44	/**
 45	 * Gets the object type managed by this search handler.
 46	 *
 47	 * @since 5.0.0
 48	 *
 49	 * @return string Object type identifier.
 50	 */
 51	public function get_type() {
 52		return $this->type;
 53	}
 54
 55	/**
 56	 * Gets the object subtypes managed by this search handler.
 57	 *
 58	 * @since 5.0.0
 59	 *
 60	 * @return string[] Array of object subtype identifiers.
 61	 */
 62	public function get_subtypes() {
 63		return $this->subtypes;
 64	}
 65
 66	/**
 67	 * Searches the object type content for a given search request.
 68	 *
 69	 * @since 5.0.0
 70	 *
 71	 * @param WP_REST_Request $request Full REST request.
 72	 * @return array Associative array containing an `WP_REST_Search_Handler::RESULT_IDS` containing
 73	 *               an array of found IDs and `WP_REST_Search_Handler::RESULT_TOTAL` containing the
 74	 *               total count for the matching search results.
 75	 */
 76	abstract public function search_items( WP_REST_Request $request );
 77
 78	/**
 79	 * Prepares the search result for a given ID.
 80	 *
 81	 * @since 5.0.0
 82	 * @since 5.6.0 The `$id` parameter can accept a string.
 83	 *
 84	 * @param int|string $id     Item ID.
 85	 * @param array      $fields Fields to include for the item.
 86	 * @return array Associative array containing all fields for the item.
 87	 */
 88	abstract public function prepare_item( $id, array $fields );
 89
 90	/**
 91	 * Prepares links for the search result of a given ID.
 92	 *
 93	 * @since 5.0.0
 94	 * @since 5.6.0 The `$id` parameter can accept a string.
 95	 *
 96	 * @param int|string $id Item ID.
 97	 * @return array Links for the given item.
 98	 */
 99	abstract public function prepare_item_links( $id );
100}
101