class.wpcom-json-api-list-terms-endpoint.php — Jetpack – WP Security, Backup, Speed, & Growth 12.4.2

jetpack / json-endpoints / class.wpcom-json-api-list-terms-endpoint.php

jetpack / json-endpoints Last commit date

class.wpcom-json-api-list-terms-endpoint.php

150 lines

1	<?php // phpcs:ignore WordPress.Files.FileName.InvalidClassFileName
2
3	/**
4	* List terms endpoint.
5	*/
6	new WPCOM_JSON_API_List_Terms_Endpoint(
7	array(
8	'description' => 'Get a list of a site\'s terms by taxonomy.',
9	'group' => 'taxonomy',
10	'stat' => 'terms',
11	'method' => 'GET',
12	'path' => '/sites/%s/taxonomies/%s/terms',
13	'path_labels' => array(
14	'$site' => '(int\|string) Site ID or domain',
15	'$taxonomy' => '(string) Taxonomy',
16	),
17	'query_parameters' => array(
18	'number' => '(int=100) The number of terms to return. Limit: 1000.',
19	'offset' => '(int=0) 0-indexed offset.',
20	'page' => '(int) Return the Nth 1-indexed page of terms. Takes precedence over the <code>offset</code> parameter.',
21	'search' => '(string) Limit response to include only terms whose names or slugs match the provided search query.',
22	'order' => array(
23	'ASC' => 'Return terms in ascending order.',
24	'DESC' => 'Return terms in descending order.',
25	),
26	'order_by' => array(
27	'name' => 'Order by the name of each tag.',
28	'count' => 'Order by the number of posts in each tag.',
29	),
30	),
31
32	'allow_fallback_to_jetpack_blog_token' => true,
33
34	'response_format' => array(
35	'found' => '(int) The number of terms returned.',
36	'terms' => '(array) Array of tag objects.',
37	),
38	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/en.blog.wordpress.com/taxonomies/post_tags/terms?number=5',
39	)
40	);
41
42	/**
43	* List terms endpoint class.
44	*
45	* /sites/%s/taxonomies/%s/terms -> $blog_id, $taxonomy
46	*/
47	class WPCOM_JSON_API_List_Terms_Endpoint extends WPCOM_JSON_API_Endpoint {
48
49	/**
50	* API callback.
51	*
52	* @param string $path - the path.
53	* @param string $blog_id - the blog ID.
54	* @param string $taxonomy - the taxonomy.
55	*/
56	public function callback( $path = '', $blog_id = 0, $taxonomy = 'category' ) {
57	$blog_id = $this->api->switch_to_blog_and_validate_user( $this->api->get_blog_id( $blog_id ) );
58	if ( is_wp_error( $blog_id ) ) {
59	return $blog_id;
60	}
61
62	if ( defined( 'IS_WPCOM' ) && IS_WPCOM ) {
63	$this->load_theme_functions();
64	}
65
66	$taxonomy_meta = get_taxonomy( $taxonomy );
67	if ( false === $taxonomy_meta \|\| ( ! $taxonomy_meta->public &&
68	! current_user_can( $taxonomy_meta->cap->assign_terms ) ) ) {
69	return new WP_Error( 'invalid_taxonomy', 'The taxonomy does not exist', 400 );
70	}
71
72	$args = $this->query_args();
73	$args = $this->process_args( $args );
74
75	$formatted_terms = $this->get_formatted_terms( $taxonomy, $args );
76
77	if ( ! empty( $formatted_terms ) ) {
78	/** This action is documented in json-endpoints/class.wpcom-json-api-site-settings-endpoint.php */
79	do_action( 'wpcom_json_api_objects', 'terms', is_countable( $formatted_terms ) ? count( $formatted_terms ) : 0 );
80	}
81
82	return array(
83	'found' => (int) $this->get_found( $taxonomy, $args ),
84	'terms' => (array) $formatted_terms,
85	);
86	}
87
88	/**
89	* Process args.
90	*
91	* @param array $args - the arguments.
92	*/
93	public function process_args( $args ) {
94	$args['get'] = 'all';
95
96	if ( $args['number'] < 1 ) {
97	$args['number'] = 100;
98	} elseif ( 1000 < $args['number'] ) {
99	return new WP_Error( 'invalid_number', 'The number parameter must be less than or equal to 1000.', 400 );
100	}
101
102	if ( isset( $args['page'] ) ) {
103	if ( $args['page'] < 1 ) {
104	$args['page'] = 1;
105	}
106
107	$args['offset'] = ( $args['page'] - 1 ) * $args['number'];
108	unset( $args['page'] );
109	}
110
111	if ( $args['offset'] < 0 ) {
112	$args['offset'] = 0;
113	}
114
115	$args['orderby'] = $args['order_by'];
116	unset( $args['order_by'] );
117
118	unset( $args['context'], $args['pretty'], $args['http_envelope'], $args['fields'] );
119	return $args;
120	}
121
122	/**
123	* Get found taxonomy term count.
124	*
125	* @param string $taxonomy - the taxonomy.
126	* @param array $args - the arguments.
127	*/
128	public function get_found( $taxonomy, $args ) {
129	unset( $args['offset'] );
130	return wp_count_terms( $taxonomy, $args );
131	}
132
133	/**
134	* Format the taxonomy terms.
135	*
136	* @param string $taxonomy - the taxonomy.
137	* @param array $args - the arguments.
138	*/
139	public function get_formatted_terms( $taxonomy, $args ) {
140	$terms = get_terms( $taxonomy, $args );
141
142	$formatted_terms = array();
143	foreach ( $terms as $term ) {
144	$formatted_terms[] = $this->format_taxonomy( $term, $taxonomy, 'display' );
145	}
146
147	return $formatted_terms;
148	}
149	}
150