← All changes | json-endpoints/class.wpcom-json-api-list-terms-endpoint.php +157 -0 16.2-beta → 16.3-beta View file →

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