CoreFiles by mySites.guru
class-wp-rest-response.php400 lines, 11,651 bytes, from wordpress-7.2-beta2.zip
Raw History Compare with 7.2-beta1
md5
c8d00e94b20bf5d2318d37909e9bbe39
sha1
4eef86abb02a8169e2fb731054d4461e95a61066
sha256
95ce0ee0283b1ae19f72c96f840aea6fb01e644339adc3f6d68becf34a8832c3
<?php
/**
 * REST API: WP_REST_Response class
 *
 * @package WordPress
 * @subpackage REST_API
 * @since 4.4.0
 */

/**
 * Core class used to implement a REST response object.
 *
 * @since 4.4.0
 *
 * @see WP_HTTP_Response
 *
 * @phpstan-import-type Route_Handler from WP_REST_Server
 * @phpstan-import-type Data_Processing from WP_REST_Server
 *
 * @phpstan-type Target_Hints array{
 *     allow?: list<uppercase-string>,
 *     ...<lowercase-string, mixed>
 * }
 * @phpstan-type Link_Attributes array{
 *     embeddable?: bool,
 *     targetHints?: Target_Hints,
 *     ...<string, mixed>
 * }
 * @phpstan-type Link array{
 *     href: non-falsy-string,
 *     attributes: Link_Attributes,
 * }
 * @phpstan-type Link_Input array{
 *     href: non-falsy-string,
 *     embeddable?: bool,
 *     targetHints?: array<string, mixed>, // Not narrowed like in Link_Attributes, since PHPStan merges this shape with its list form in add_links(). The merged attributes passed to add_link() there are only accepted while they include `mixed`; with the nested shape, the call would be an argument.type error even when `mixed` is not checked.
 *     ...<string, mixed>
 * }
 * @phpstan-type Curie array{
 *     name: string, // An empty name is a valid empty CURIE prefix, which WP_REST_Server::get_compact_response_links() handles consistently.
 *     href: non-falsy-string,
 *     templated?: bool,
 * }
 */
class WP_REST_Response extends WP_HTTP_Response {

	/**
	 * Links related to the response.
	 *
	 * @since 4.4.0
	 * @var array<string, array<string, mixed>[]> Map of link relation to list of links.
	 * @phpstan-var array<non-falsy-string, array<Link>>
	 */
	protected $links = array();

	/**
	 * The route that was to create the response.
	 *
	 * @since 4.4.0
	 * @var string
	 */
	protected $matched_route = '';

	/**
	 * The handler that was used to create the response.
	 *
	 * @since 4.4.0
	 * @var array<string, mixed>|null
	 * @phpstan-var Route_Handler|null
	 */
	protected $matched_handler = null;

	/**
	 * Whether each data processing feature is on for the response.
	 *
	 * @since 7.2.0
	 * @var array<string, bool> Whether the `fields`, `embed` and `links` features are on. Every feature is on by default.
	 * @phpstan-var Data_Processing
	 */
	protected $data_processing = array(
		'fields' => true,
		'embed'  => true,
		'links'  => true,
	);

	/**
	 * Adds a link to the response.
	 *
	 * {@internal The $rel parameter is first, as this looks nicer when sending multiple.}
	 *
	 * @since 4.4.0
	 *
	 * @link https://tools.ietf.org/html/rfc5988
	 * @link https://www.iana.org/assignments/link-relations/link-relations.xml
	 *
	 * @param string               $rel        Link relation. Either an IANA registered type,
	 *                                         or an absolute URL.
	 * @param string               $href       Target URI for the link.
	 * @param array<string, mixed> $attributes Optional. Link parameters to send along with the URL. Default empty array.
	 *
	 * @phpstan-param non-falsy-string $rel
	 * @phpstan-param non-falsy-string $href
	 * @phpstan-param Link_Attributes  $attributes
	 */
	public function add_link( $rel, $href, $attributes = array() ) {
		if ( empty( $this->links[ $rel ] ) ) {
			$this->links[ $rel ] = array();
		}

		if ( isset( $attributes['href'] ) ) {
			// Remove the href attribute, as it's used for the main URL.
			unset( $attributes['href'] );
		}

		$this->links[ $rel ][] = array(
			'href'       => $href,
			'attributes' => $attributes,
		);
	}

	/**
	 * Removes a link from the response.
	 *
	 * @since 4.4.0
	 *
	 * @param string      $rel  Link relation. Either an IANA registered type, or an absolute URL.
	 * @param string|null $href Optional. Only remove links for the relation matching the given href.
	 *                          Default null.
	 *
	 * @phpstan-param non-falsy-string $rel
	 */
	public function remove_link( $rel, $href = null ) {
		if ( ! isset( $this->links[ $rel ] ) ) {
			return;
		}

		if ( $href ) {
			$this->links[ $rel ] = wp_list_filter( $this->links[ $rel ], array( 'href' => $href ), 'NOT' );
		} else {
			$this->links[ $rel ] = array();
		}

		if ( ! $this->links[ $rel ] ) {
			unset( $this->links[ $rel ] );
		}
	}

	/**
	 * Adds multiple links to the response.
	 *
	 * Link data should be an associative array with link relation as the key.
	 * The value can either be an associative array of link attributes
	 * (including `href` with the URL for the response), or a list of these
	 * associative arrays.
	 *
	 * @since 4.4.0
	 *
	 * @param array<string, array<mixed>> $links Map of link relation to a link's attributes, or to a list of these.
	 *
	 * @phpstan-param array<non-falsy-string, Link_Input|list<Link_Input>> $links
	 */
	public function add_links( $links ) {
		foreach ( $links as $rel => $set ) {
			// If it's a single link, wrap with an array for consistent handling.
			if ( isset( $set['href'] ) ) {
				$set = array( $set );
			}

			foreach ( $set as $attributes ) {
				$this->add_link( $rel, $attributes['href'], $attributes );
			}
		}
	}

	/**
	 * Retrieves links for the response.
	 *
	 * @since 4.4.0
	 *
	 * @return array<string, array<string, mixed>[]> Map of link relation to list of links.
	 *
	 * @phpstan-return array<non-falsy-string, array<Link>>
	 */
	public function get_links() {
		return $this->links;
	}

	/**
	 * Sets a single link header.
	 *
	 * {@internal The $rel parameter is first, as this looks nicer when sending multiple.}
	 *
	 * @since 4.4.0
	 *
	 * @link https://tools.ietf.org/html/rfc5988
	 * @link https://www.iana.org/assignments/link-relations/link-relations.xml
	 *
	 * @param string                $rel   Link relation. Either an IANA registered type, or an absolute URL.
	 * @param string                $link  Target IRI for the link.
	 * @param array<string, string> $other Optional. Other parameters to send, as an associative array.
	 *                                     Default empty array.
	 *
	 * @phpstan-param non-falsy-string $rel
	 */
	public function link_header( $rel, $link, $other = array() ) {
		$header = '<' . $link . '>; rel="' . $rel . '"';

		foreach ( $other as $key => $value ) {
			if ( 'title' === $key ) {
				$value = '"' . $value . '"';
			}

			$header .= '; ' . $key . '=' . $value;
		}
		$this->header( 'Link', $header, false );
	}

	/**
	 * Retrieves the route that was used.
	 *
	 * @since 4.4.0
	 *
	 * @return string The matched route.
	 */
	public function get_matched_route() {
		return $this->matched_route;
	}

	/**
	 * Sets the route (regex for path) that caused the response.
	 *
	 * @since 4.4.0
	 *
	 * @param string $route Route name.
	 */
	public function set_matched_route( $route ) {
		$this->matched_route = $route;
	}

	/**
	 * Retrieves the handler that was used to generate the response.
	 *
	 * @since 4.4.0
	 *
	 * @return array<string, mixed>|null The handler that was used to create the response.
	 *
	 * @phpstan-return Route_Handler|null
	 */
	public function get_matched_handler() {
		return $this->matched_handler;
	}

	/**
	 * Sets the handler that was responsible for generating the response.
	 *
	 * @since 4.4.0
	 *
	 * @param array<string, mixed> $handler The matched handler.
	 *
	 * @phpstan-param Route_Handler $handler
	 */
	public function set_matched_handler( $handler ) {
		$this->matched_handler = $handler;
	}

	/**
	 * Retrieves whether each data processing feature is on for the response.
	 *
	 * The server sets the settings of the matched route when it dispatches a request, for responses
	 * returned by the `rest_pre_dispatch` filter too. Every feature is on until then.
	 *
	 * @since 7.2.0
	 *
	 * @see WP_REST_Server::resolve_data_processing()
	 *
	 * @return array<string, bool> {
	 *     Whether each data processing feature is on.
	 *
	 *     @type bool $fields Whether the `_fields` parameter filters the response data.
	 *     @type bool $embed  Whether the `_embed` parameter embeds linked resources in the response data.
	 *     @type bool $links  Whether the response links are added to the response data as `_links`.
	 * }
	 *
	 * @phpstan-return Data_Processing
	 */
	public function get_data_processing() {
		return $this->data_processing;
	}

	/**
	 * Sets whether each data processing feature is on for the response.
	 *
	 * The setting takes the form of the `data_processing` route option: `false` turns off every
	 * feature, and an array turns off, or on, the features it names. Embedding needs the links, so
	 * `embed` is off whenever `links` is off.
	 *
	 * @since 7.2.0
	 *
	 * @see WP_REST_Server::resolve_data_processing()
	 *
	 * @param bool|array<string, bool> $processing Whether every feature is on, or whether the `fields`, `embed`
	 *                                             and `links` features are on. A feature not named stays on.
	 *
	 * @phpstan-param bool|array{fields?: bool, embed?: bool, links?: bool} $processing
	 */
	public function set_data_processing( $processing ) {
		$this->data_processing = WP_REST_Server::resolve_data_processing( array( 'data_processing' => $processing ) );
	}

	/**
	 * Checks if the response is an error, i.e. >= 400 response code.
	 *
	 * @since 4.4.0
	 *
	 * @return bool Whether the response is an error.
	 */
	public function is_error() {
		return $this->get_status() >= 400;
	}

	/**
	 * Retrieves a WP_Error object from the response.
	 *
	 * @since 4.4.0
	 *
	 * @return WP_Error|null WP_Error or null on not an errored response.
	 */
	public function as_error() {
		if ( ! $this->is_error() ) {
			return null;
		}

		$error = new WP_Error();

		if ( is_array( $this->get_data() ) ) {
			$data = $this->get_data();
			$error->add( $data['code'], $data['message'], $data['data'] );

			if ( ! empty( $data['additional_errors'] ) ) {
				foreach ( $data['additional_errors'] as $err ) {
					$error->add( $err['code'], $err['message'], $err['data'] );
				}
			}
		} else {
			$error->add( $this->get_status(), '', array( 'status' => $this->get_status() ) );
		}

		return $error;
	}

	/**
	 * Retrieves the CURIEs (compact URIs) used for relations.
	 *
	 * @since 4.5.0
	 *
	 * @return array<string, string|bool>[] Compact URIs.
	 *
	 * @phpstan-return array<Curie>
	 */
	public function get_curies() {
		$curies = array(
			array(
				'name'      => 'wp',
				'href'      => 'https://api.w.org/{rel}',
				'templated' => true,
			),
		);

		/**
		 * Filters extra CURIEs available on REST API responses.
		 *
		 * CURIEs allow a shortened version of URI relations. This allows a more
		 * usable form for custom relations than using the full URI. These work
		 * similarly to how XML namespaces work.
		 *
		 * Registered CURIES need to specify a name and URI template. This will
		 * automatically transform URI relations into their shortened version.
		 * The shortened relation follows the format `{name}:{rel}`. `{rel}` in
		 * the URI template will be replaced with the `{rel}` part of the
		 * shortened relation.
		 *
		 * For example, a CURIE with name `example` and URI template
		 * `http://w.org/{rel}` would transform a `http://w.org/term` relation
		 * into `example:term`.
		 *
		 * Well-behaved clients should expand and normalize these back to their
		 * full URI relation, however some naive clients may not resolve these
		 * correctly, so adding new CURIEs may break backward compatibility.
		 *
		 * @since 4.5.0
		 *
		 * @param array<string, string|bool>[] $additional Additional CURIEs to register with the REST API.
		 *
		 * @phpstan-param array<Curie> $additional
		 */
		$additional = apply_filters( 'rest_response_link_curies', array() );

		return array_merge( $curies, $additional );
	}
}

The same content is in 3 releases, WordPress 7.2-beta2 to 7.2-beta4. See them all, or every version of this file.