betterdocs / includes / Abilities / Terms / UpdateTerm.php

UpdateTerm.php in BetterDocs – AI Documentation, Knowledge Base, MCP Server, Docs, Wikis, FAQ & Chatbot 4.9.2, at includes/Abilities/Terms/UpdateTerm.php

179 lines 4.9 KB

Raw Download Zip

1	<?php
2	/**
3	* Update a doc category or doc tag ability.
4	*
5	* @package BetterDocs
6	* @since 4.9.0
7	*/
8
9	namespace WPDeveloper\BetterDocs\Abilities\Terms;
10
11	if ( ! defined( 'ABSPATH' ) ) {
12	exit; // Exit if accessed directly.
13	}
14
15	use WPDeveloper\BetterDocs\Abilities\AbilityError;
16
17	/**
18	* Rename a term, move it, re-describe it, or change which knowledge bases a
19	* doc category belongs to.
20	*
21	* `knowledge_bases` replaces the list, so `[]` clears it — the same rule the
22	* Docs tools use for term arrays, and the reason it is spelled out in the field
23	* description rather than left to be discovered.
24	*
25	* Changing a doc category's knowledge bases changes its permalink: the KB
26	* slug is a path segment (`/docs/<kb>/<category>/`). Worth knowing before an
27	* agent tidies up somebody's taxonomy.
28	*
29	* @since 4.9.0
30	*/
31	class UpdateTerm extends CreateTerm {
32
33	/**
34	* @since 4.9.0
35	*/
36	public function __construct() {
37	parent::__construct();
38
39	$this->id = 'betterdocs/update-term';
40	$this->label = __( 'Update term', 'betterdocs' );
41	$this->description = __( 'Update a BetterDocs doc category or doc tag by id. Only the fields you send change. knowledge_bases REPLACES the list a doc category belongs to — send [] to clear it. Changing it also changes the category permalink, because the knowledge base slug is part of the URL.', 'betterdocs' );
42	$this->capability = 'edit_doc_terms';
43	}
44
45	/**
46	* @since 4.9.0
47	*
48	* @return array
49	*/
50	public function get_annotations() {
51	return [
52	'readonly' => false,
53	'destructive' => false,
54	'idempotent' => true,
55	'priority' => 2.0,
56	'openWorldHint' => false
57	];
58	}
59
60	/**
61	* @since 4.9.0
62	*
63	* @return array
64	*/
65	public function get_input_schema() {
66	$schema = parent::get_input_schema();
67
68	$schema['required'] = [ 'taxonomy', 'id' ];
69
70	$schema['properties']['name']['description'] = __( 'A new name. Omit to leave it alone.', 'betterdocs' );
71
72	$schema['properties']['knowledge_bases']['description'] = __( 'REPLACES the knowledge bases this doc category belongs to, by id, slug or name. Send [] to clear it, omit to leave it alone. Never created here.', 'betterdocs' );
73
74	$schema['properties'] = array_merge(
75	[
76	'taxonomy' => $schema['properties']['taxonomy'],
77	'id' => [
78	'type' => 'integer',
79	'description' => __( 'The term id to update. Required.', 'betterdocs' )
80	]
81	],
82	$schema['properties']
83	);
84
85	return $schema;
86	}
87
88	/**
89	* @since 4.9.0
90	*
91	* @param array $input Validated input.
92	* @return array\|\WP_Error
93	*/
94	public function execute( $input ) {
95	$taxonomy = isset( $input['taxonomy'] ) ? (string) $input['taxonomy'] : '';
96
97	// Before anything is read or written: a taxonomy that is switched off
98	// answers with the setting to change, not with `not_found` (ADR-061).
99	$available = $this->taxonomy_available( $taxonomy );
100
101	if ( is_wp_error( $available ) ) {
102	return $available;
103	}
104
105	$term = $this->require_term( isset( $input['id'] ) ? $input['id'] : 0, $taxonomy );
106
107	if ( is_wp_error( $term ) ) {
108	return $term;
109	}
110
111	$params = $this->build_params( $input, $taxonomy );
112
113	if ( is_wp_error( $params ) ) {
114	return $params;
115	}
116
117	// Before the rename is written, so a knowledge base that cannot be
118	// assigned does not leave the term half-updated.
119	$kb_slugs = $this->resolve_kb_input( $input, $taxonomy );
120
121	if ( is_wp_error( $kb_slugs ) ) {
122	return $kb_slugs;
123	}
124
125	if ( [] === $params && ! isset( $input['knowledge_bases'] ) ) {
126	return AbilityError::invalid_input(
127	'input',
128	__( 'Nothing to update: send at least one field besides taxonomy and id.', 'betterdocs' )
129	);
130	}
131
132	$updated = (array) $term;
133
134	if ( [] !== $params ) {
135	$response = $this->dispatch( 'POST', '/' . $taxonomy . '/' . (int) $term->term_id, $params, 'wp/v2' );
136
137	if ( is_wp_error( $response ) ) {
138	return $this->map_term_error(
139	$response,
140	$taxonomy,
141	sprintf(
142	/* translators: 1: term type, 2: term id. */
143	__( 'edit %1$s #%2$d', 'betterdocs' ),
144	$this->term_object_name( $taxonomy ),
145	(int) $term->term_id
146	)
147	);
148	}
149
150	$updated = (array) $response;
151	}
152
153	if ( null !== $kb_slugs ) {
154	$assigned = $this->assign_knowledge_bases( (int) $term->term_id, $kb_slugs );
155
156	if ( is_wp_error( $assigned ) ) {
157	return $assigned;
158	}
159
160	$updated = $assigned;
161	}
162
163	if ( empty( $updated['id'] ) ) {
164	// Nothing was dispatched (the caller sent only `knowledge_bases: []`
165	// on a category that had none), so read the term back rather than
166	// answering from a `WP_Term` that has different keys.
167	$read = $this->dispatch( 'GET', '/' . $taxonomy . '/' . (int) $term->term_id, [ 'context' => 'view' ], 'wp/v2' );
168
169	if ( is_wp_error( $read ) ) {
170	return $this->map_term_error( $read, $taxonomy, __( 'read the term back', 'betterdocs' ) );
171	}
172
173	$updated = (array) $read;
174	}
175
176	return array_merge( $this->term_shape( $updated, $taxonomy ), [ 'created' => false ] );
177	}
178	}
179