convertkit / includes / mcp / abilities / category-settings / class-convertkit-mcp-ability-category-settings.php

class-convertkit-mcp-ability-category-settings.php in Kit (formerly ConvertKit) – Email Newsletter, Email Marketing, Membership, Subscribers and Landing Pages 3.4.4, at includes/mcp/abilities/category-settings/class-convertkit-mcp-ability-category-settings.php

188 lines 4.5 KB

Raw Download Zip

1	<?php
2	/**
3	* Kit MCP Ability: Category Settings base class.
4	*
5	* @package ConvertKit
6	* @author ConvertKit
7	*/
8
9	/**
10	* Base class for abilities that read or update the per-Category Kit settings
11	* (form, form_position) stored in the `_wp_convertkit_term_meta` term meta key.
12	*
13	* Each subclass represents a single verb (get / update). Produces ability
14	* names of the form `kit/category-settings-<operation>`.
15	*
16	* Scope is limited to the `category` taxonomy, matching the admin UI
17	* (ConvertKit_Admin_Category) and the frontend read path
18	* (ConvertKit_Output::get_term_form_position()).
19	*
20	* @package ConvertKit
21	* @author ConvertKit
22	*/
23	abstract class ConvertKit_MCP_Ability_Category_Settings extends ConvertKit_MCP_Ability {
24
25	/**
26	* The taxonomy this ability operates on.
27	*
28	* @since 3.4.0
29	*
30	* @var string
31	*/
32	const TAXONOMY = 'category';
33
34	/**
35	* Returns the operation suffix used in the ability name (e.g. 'get',
36	* 'update').
37	*
38	* @since 3.4.0
39	*
40	* @return string
41	*/
42	abstract protected function get_operation();
43
44	/**
45	* Returns the ability name.
46	*
47	* @since 3.4.0
48	*
49	* @return string
50	*/
51	public function get_name() {
52
53	return 'kit/category-settings-' . $this->get_operation();
54
55	}
56
57	/**
58	* Only permit an ability to be executed if the current user can edit
59	* the given category term.
60	*
61	* @since 3.4.0
62	*
63	* @param array $input Ability input.
64	* @return bool\|WP_Error
65	*/
66	public function permission_callback( $input ) {
67
68	// Get Term ID.
69	$term_id = isset( $input['term_id'] ) ? absint( $input['term_id'] ) : 0;
70
71	// Bail if no Term ID is provided.
72	if ( ! $term_id ) {
73	return new WP_Error(
74	'convertkit_mcp_missing_term_id',
75	__( 'A term_id is required.', 'convertkit' )
76	);
77	}
78
79	// Bail if the current user cannot edit this term.
80	if ( ! current_user_can( 'edit_term', $term_id ) ) {
81	return new WP_Error(
82	'convertkit_mcp_cannot_edit_term',
83	__( 'You do not have permission to edit this category.', 'convertkit' )
84	);
85	}
86
87	return true;
88
89	}
90
91	/**
92	* Validates that the given term exists and is in the `category` taxonomy.
93	*
94	* Returned as a shared helper for both verb subclasses' execute_callback.
95	*
96	* @since 3.4.0
97	*
98	* @param int $term_id Term ID.
99	* @return true\|WP_Error
100	*/
101	protected function validate_term( $term_id ) {
102
103	$term = get_term( $term_id );
104
105	// Bail if the term does not exist.
106	if ( ! $term \|\| is_wp_error( $term ) ) {
107	return new WP_Error(
108	'convertkit_mcp_term_not_found',
109	sprintf(
110	/* translators: %d: Term ID. */
111	__( 'Term %d does not exist.', 'convertkit' ),
112	$term_id
113	)
114	);
115	}
116
117	// Bail if the term is not in the `category` taxonomy.
118	if ( $term->taxonomy !== self::TAXONOMY ) {
119	return new WP_Error(
120	'convertkit_mcp_term_wrong_taxonomy',
121	sprintf(
122	/* translators: 1: Term ID, 2: Actual taxonomy, 3: Expected taxonomy. */
123	__( 'Term %1$d is in the "%2$s" taxonomy; this ability only supports the "%3$s" taxonomy.', 'convertkit' ),
124	$term_id,
125	$term->taxonomy,
126	self::TAXONOMY
127	)
128	);
129	}
130
131	return true;
132
133	}
134
135	/**
136	* Returns the JSON Schema properties that describe the two Kit category
137	* settings, shared by both the input and output schemas.
138	*
139	* @since 3.4.0
140	*
141	* @return array
142	*/
143	protected function get_settings_schema_properties() {
144
145	return array(
146	'form' => array(
147	'type' => 'integer',
148	'description' => __( 'Form to display for Posts assigned to this Category. `-1` = use the Plugin Default Form; `0` = display no form; any other positive integer is a specific Kit Form ID.', 'convertkit' ),
149	'minimum' => -1,
150	),
151	'form_position' => array(
152	'type' => 'string',
153	'description' => __( 'Where the Form displays on the Category archive page. Empty string uses the Plugin default position; `before` displays it before the post list; `after` displays it after.', 'convertkit' ),
154	'enum' => array( '', 'before', 'after' ),
155	),
156	);
157
158	}
159
160	/**
161	* Returns the JSON Schema for the ability's output.
162	*
163	* Shared by get and update so a caller can chain update -> confirm.
164	*
165	* @since 3.4.0
166	*
167	* @return array
168	*/
169	public function get_output_schema() {
170
171	return array(
172	'type' => 'object',
173	'required' => array( 'term_id', 'form', 'form_position' ),
174	'properties' => array_merge(
175	array(
176	'term_id' => array(
177	'type' => 'integer',
178	'description' => __( 'The Category (term) ID.', 'convertkit' ),
179	),
180	),
181	$this->get_settings_schema_properties()
182	),
183	);
184
185	}
186
187	}
188