betterdocs / includes / Abilities / Faq / UpdateFAQGroup.php

UpdateFAQGroup.php in BetterDocs – AI Documentation, Knowledge Base, MCP Server, Docs, Wikis, FAQ & Chatbot 4.9.1, at includes/Abilities/Faq/UpdateFAQGroup.php

195 lines 5.2 KB

Raw Download Zip

1	<?php
2	/**
3	* Update an FAQ group ability.
4	*
5	* @package BetterDocs
6	* @since 4.9.0
7	*/
8
9	namespace WPDeveloper\BetterDocs\Abilities\Faq;
10
11	if ( ! defined( 'ABSPATH' ) ) {
12	exit; // Exit if accessed directly.
13	}
14
15	use WPDeveloper\BetterDocs\Abilities\AbilityError;
16
17	/**
18	* Rename an FAQ group, change its description or slug, or switch it on and off.
19	*
20	* Extends {@see CreateFAQGroup} so the two accept the same fields with the
21	* same meanings, all optional here.
22	*
23	* Everything unnamed is preserved, deliberately.
24	* `FAQBuilder::update_faq_category()` hands its parameters to
25	* `wp_update_term()` unfiltered, so a call carrying only a new title would
26	* blank the description and the slug — and its `update_term_meta( …,
27	* 'faq_group_icon', … )` would wipe the group's icon as well. This reads the
28	* group first and sends the whole record, so an omitted field means "leave it".
29	*
30	* @since 4.9.0
31	*/
32	class UpdateFAQGroup extends CreateFAQGroup {
33
34	/**
35	* @since 4.9.0
36	*/
37	public function __construct() {
38	parent::__construct();
39
40	$this->id = 'betterdocs/update-faq-group';
41	$this->label = __( 'Update FAQ group', 'betterdocs' );
42	$this->description = __( 'Rename a BetterDocs FAQ group, change its description or slug, or switch it between publish and draft (the FAQ Builder\'s enabled/disabled switch). Fields you leave out keep their current values.', 'betterdocs' );
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'] = [ 'id' ];
69
70	unset( $schema['properties']['status']['default'] );
71
72	$schema['properties'] = array_merge(
73	[
74	'id' => [
75	'type' => 'integer',
76	'description' => __( 'The FAQ group id. Required.', 'betterdocs' )
77	]
78	],
79	$schema['properties']
80	);
81
82	$schema['properties']['title']['description'] = __( 'A new name for the group. Left alone when omitted; changing it does not change the slug.', 'betterdocs' );
83	$schema['properties']['slug']['description'] = __( 'A new URL slug. Left alone when omitted.', 'betterdocs' );
84
85	return $schema;
86	}
87
88	/**
89	* @since 4.9.0
90	*
91	* @return array
92	*/
93	public function get_output_schema() {
94	return [
95	'type' => 'object',
96	'properties' => self::group_shape_schema()
97	];
98	}
99
100	/**
101	* @since 4.9.0
102	*
103	* @param array $input Validated input.
104	* @return array\|\WP_Error
105	*/
106	public function execute( $input ) {
107	$id = isset( $input['id'] ) ? (int) $input['id'] : 0;
108	$current = $this->group_item( $id );
109
110	if ( is_wp_error( $current ) ) {
111	return $current;
112	}
113
114	$fields = [ 'title', 'description', 'slug', 'status' ];
115	$given = array_intersect_key( $input, array_flip( $fields ) );
116
117	if ( empty( $given ) ) {
118	return AbilityError::invalid_input(
119	'input',
120	__( 'Nothing to update: send at least one of title, description, slug or status.', 'betterdocs' )
121	);
122	}
123
124	if ( isset( $input['title'] ) && '' === trim( (string) $input['title'] ) ) {
125	return AbilityError::invalid_input( 'title', __( 'An FAQ group needs a name.', 'betterdocs' ) );
126	}
127
128	$written = $this->write_group( $id, $input, $current );
129
130	if ( is_wp_error( $written ) ) {
131	return $written;
132	}
133
134	if ( isset( $input['status'] ) ) {
135	$status = $this->apply_group_status( $id, (string) $input['status'], false );
136
137	if ( is_wp_error( $status ) ) {
138	return $status;
139	}
140	}
141
142	$item = $this->group_item( $id );
143
144	if ( is_wp_error( $item ) ) {
145	return $item;
146	}
147
148	return $this->group_shape( $item );
149	}
150
151	/**
152	* Send the whole record to `faq/update_category`, merged over what the group
153	* holds now.
154	*
155	* Skipped entirely when only `status` was sent, so a switch on or off never
156	* rewrites the term row.
157	*
158	* @since 4.9.0
159	*
160	* @param int $id Group id.
161	* @param array $input Validated input.
162	* @param array $current The group as it is now.
163	* @return true\|\WP_Error
164	*/
165	protected function write_group( $id, array $input, array $current ) {
166	$changes = array_intersect_key( $input, array_flip( [ 'title', 'description', 'slug' ] ) );
167
168	if ( empty( $changes ) ) {
169	return true;
170	}
171
172	$params = [
173	'term_id' => $id,
174	'title' => isset( $input['title'] ) ? (string) $input['title'] : (string) $current['name'],
175	'description' => isset( $input['description'] ) ? (string) $input['description'] : (string) $current['description'],
176	'slug' => isset( $input['slug'] ) ? (string) $input['slug'] : (string) $current['slug'],
177	// Preserved by hand: the route writes this meta on every call, so
178	// omitting it would delete the group's icon.
179	'group_icon_url' => (string) $this->term_meta_first( $current, 'faq_group_icon', '' )
180	];
181
182	$result = $this->dispatch( 'POST', '/faq/update_category', $params, self::FAQ_NS );
183
184	if ( is_wp_error( $result ) ) {
185	return $this->map_faq_error( $result, __( 'update an FAQ group', 'betterdocs' ) );
186	}
187
188	if ( true !== $result ) {
189	return AbilityError::upstream( __( 'BetterDocs did not confirm the FAQ group update.', 'betterdocs' ) );
190	}
191
192	return true;
193	}
194	}
195