WP_REST_Posts_Controller::prepare_taxonomy_limit_schema( array $query_params ): array

In this article

This function’s access is marked private. This means it is not intended for use by plugin or theme developers, only in other core functions. It is listed here for completeness.

Prepares the collection schema for including and excluding items by terms.

Parameters

$query_paramsarrayrequired
Collection schema.

Return

array Updated schema.

Source

private function prepare_taxonomy_limit_schema( array $query_params ) {
	$taxonomies = wp_list_filter( get_object_taxonomies( $this->post_type, 'objects' ), array( 'show_in_rest' => true ) );

	if ( ! $taxonomies ) {
		return $query_params;
	}

	$query_params['tax_relation'] = array(
		'description' => __( 'Limit result set based on relationship between multiple taxonomies.' ),
		'type'        => 'string',
		'enum'        => array( 'AND', 'OR' ),
	);

	$limit_schema = array(
		'type'  => array( 'object', 'array' ),
		'oneOf' => array(
			array(
				'title'       => __( 'Term ID List' ),
				'description' => __( 'Match terms with the listed IDs.' ),
				'type'        => 'array',
				'items'       => array(
					'type' => 'integer',
				),
			),
			array(
				'title'                => __( 'Term ID Taxonomy Query' ),
				'description'          => __( 'Perform an advanced term query.' ),
				'type'                 => 'object',
				'properties'           => array(
					'terms'            => array(
						'description' => __( 'Term IDs.' ),
						'type'        => 'array',
						'items'       => array(
							'type' => 'integer',
						),
						'default'     => array(),
					),
					'include_children' => array(
						'description' => __( 'Whether to include child terms in the terms limiting the result set.' ),
						'type'        => 'boolean',
						'default'     => false,
					),
				),
				'additionalProperties' => false,
			),
		),
	);

	$include_schema = array_merge(
		array(
			/* translators: %s: Taxonomy name. */
			'description' => __( 'Limit result set to items with specific terms assigned in the %s taxonomy.' ),
		),
		$limit_schema
	);
	// 'operator' is supported only for 'include' queries.
	$include_schema['oneOf'][1]['properties']['operator'] = array(
		'description' => __( 'Whether items must be assigned all or any of the specified terms.' ),
		'type'        => 'string',
		'enum'        => array( 'AND', 'OR' ),
		'default'     => 'OR',
	);

	$exclude_schema = array_merge(
		array(
			/* translators: %s: Taxonomy name. */
			'description' => __( 'Limit result set to items except those with specific terms assigned in the %s taxonomy.' ),
		),
		$limit_schema
	);

	foreach ( $taxonomies as $taxonomy ) {
		$base         = ! empty( $taxonomy->rest_base ) ? $taxonomy->rest_base : $taxonomy->name;
		$base_exclude = $base . '_exclude';

		$query_params[ $base ]                = $include_schema;
		$query_params[ $base ]['description'] = sprintf( $query_params[ $base ]['description'], $base );

		$query_params[ $base_exclude ]                = $exclude_schema;
		$query_params[ $base_exclude ]['description'] = sprintf( $query_params[ $base_exclude ]['description'], $base );

		if ( ! $taxonomy->hierarchical ) {
			unset( $query_params[ $base ]['oneOf'][1]['properties']['include_children'] );
			unset( $query_params[ $base_exclude ]['oneOf'][1]['properties']['include_children'] );
		}
	}

	return $query_params;
}

Changelog

VersionDescription
5.7.0Introduced.

User Contributed Notes

You must log in before being able to contribute a note or feedback.