convertkit / includes / mcp / abilities / content / class-convertkit-mcp-ability-content-list.php

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

189 lines 3.9 KB

Raw Download Zip

1	<?php
2	/**
3	* Kit MCP Ability: List Kit Elements in a post.
4	*
5	* @package ConvertKit
6	* @author ConvertKit
7	*/
8
9	/**
10	* Ability that lists all occurrences of a given Kit element
11	* (Broadcast, Form, Form Trigger, Product) within a WordPress Post's content.
12	*
13	* Registered by an element opting in via the `convertkit_abilities` filter and
14	* produces an ability named `kit/<element>-list` (e.g. `kit/form-list`).
15	*
16	* @package ConvertKit
17	* @author ConvertKit
18	*/
19	class ConvertKit_MCP_Ability_Content_List extends ConvertKit_MCP_Ability_Content {
20
21	/**
22	* Sets whether the ability is readonly.
23	*
24	* @since 3.4.0
25	*
26	* @var bool
27	*/
28	private $readonly = true; // @phpstan-ignore-line
29
30	/**
31	* Sets whether the ability is idempotent.
32	*
33	* @since 3.4.0
34	*
35	* @var bool
36	*/
37	private $idempotent = true; // @phpstan-ignore-line
38
39	/**
40	* Returns the verb this ability represents.
41	*
42	* @since 3.4.0
43	*
44	* @return string
45	*/
46	public function get_verb() {
47
48	return 'list';
49
50	}
51
52	/**
53	* Returns the ability's human-readable label.
54	*
55	* @since 3.4.0
56	*
57	* @return string
58	*/
59	public function get_label() {
60
61	return sprintf(
62	/* translators: %s: block title */
63	__( 'List %s in a Post, Page or Custom Post', 'convertkit' ),
64	$this->block->get_title_plural()
65	);
66
67	}
68
69	/**
70	* Returns the ability's human-readable description.
71	*
72	* @since 3.4.0
73	*
74	* @return string
75	*/
76	public function get_description() {
77
78	return sprintf(
79	/* translators: Block Name */
80	__( 'Lists every %s in the given Post, Page or Custom Post, including each occurrence\'s zero-based index and current attribute values.', 'convertkit' ),
81	$this->block->get_title_plural()
82	);
83
84	}
85
86	/**
87	* Returns the ability's input JSON Schema.
88	*
89	* @since 3.4.0
90	*
91	* @return array
92	*/
93	public function get_input_schema() {
94
95	return array(
96	'type' => 'object',
97	'required' => array( 'post_id' ),
98	'properties' => array(
99	'post_id' => array(
100	'type' => 'integer',
101	'minimum' => 1,
102	'description' => __( 'ID of the post to inspect.', 'convertkit' ),
103	),
104	),
105	);
106
107	}
108
109	/**
110	* Returns the ability's output JSON Schema.
111	*
112	* @since 3.4.0
113	*
114	* @return array
115	*/
116	public function get_output_schema() {
117
118	return array(
119	'type' => 'object',
120	'required' => array( 'post_id', 'count', 'occurrences' ),
121	'properties' => array(
122	'post_id' => array(
123	'type' => 'integer',
124	),
125	'count' => array(
126	'type' => 'integer',
127	'minimum' => 0,
128	),
129	'occurrences' => array(
130	'type' => 'array',
131	'items' => array(
132	'type' => 'object',
133	'required' => array( 'occurrence_index', 'attrs' ),
134	'properties' => array(
135	'occurrence_index' => array(
136	'type' => 'integer',
137	'minimum' => 0,
138	'description' => __( 'Zero-based occurrence index among this element\'s appearances in the post.', 'convertkit' ),
139	),
140	'attrs' => array(
141	'type' => 'object',
142	'description' => __( 'Element attributes for this occurrence.', 'convertkit' ),
143	),
144	),
145	),
146	),
147	),
148	);
149
150	}
151
152	/**
153	* Executes the ability.
154	*
155	* @since 3.4.0
156	*
157	* @param array $input Ability input.
158	* @return array\|WP_Error
159	*/
160	public function execute_callback( $input ) {
161
162	// Get Post ID.
163	$post_id = isset( $input['post_id'] ) ? absint( $input['post_id'] ) : 0;
164
165	// Bail if no Post ID is provided.
166	if ( ! $post_id ) {
167	return new WP_Error(
168	'convertkit_mcp_missing_post_id',
169	__( 'A post_id is required.', 'convertkit' )
170	);
171	}
172
173	// Find element occurrences in post.
174	$occurrences = ConvertKit_Content_Post_Helper::find( $post_id, $this->block->get_name() );
175	if ( is_wp_error( $occurrences ) ) {
176	return $occurrences;
177	}
178
179	// Return result.
180	return array(
181	'post_id' => $post_id,
182	'count' => count( $occurrences ),
183	'occurrences' => $occurrences,
184	);
185
186	}
187
188	}
189