stream / classes / class-ability.php

class-ability.php in Stream – Activity Log & Audit Trail 4.2.2, at classes/class-ability.php

165 lines 4.2 KB

Raw Download Zip

1	<?php
2	/**
3	* Abstract base class for Stream abilities (WordPress Abilities API integration).
4	*
5	* @package WP_Stream
6	*/
7
8	namespace WP_Stream;
9
10	/**
11	* Class - Ability
12	*
13	* Subclasses define a single Stream operation that is exposed via the
14	* WordPress Abilities API. Each subclass declares a namespaced name,
15	* input/output JSON Schemas, a permission callback, and an execute
16	* callback. Subclasses are instantiated and registered by Abilities.
17	*/
18	abstract class Ability {
19
20	/**
21	* Holds instance of plugin object.
22	*
23	* @var Plugin
24	*/
25	protected $plugin;
26
27	/**
28	* Class constructor.
29	*
30	* @param Plugin $plugin Instance of plugin object.
31	*/
32	public function __construct( Plugin $plugin ) {
33	$this->plugin = $plugin;
34	}
35
36	/**
37	* Namespaced ability name (e.g. "stream/get-records").
38	*
39	* @return string
40	*/
41	abstract public function get_name();
42
43	/**
44	* Short human-readable label.
45	*
46	* @return string
47	*/
48	abstract public function get_label();
49
50	/**
51	* Description of what the ability does.
52	*
53	* @return string
54	*/
55	abstract public function get_description();
56
57	/**
58	* JSON Schema for ability input. Return an empty array for no input.
59	*
60	* @return array
61	*/
62	abstract public function get_input_schema();
63
64	/**
65	* JSON Schema for ability output.
66	*
67	* @return array
68	*/
69	abstract public function get_output_schema();
70
71	/**
72	* Execute the ability.
73	*
74	* The default value is `null` to match WP core's invoke_callback() contract:
75	* when an ability has no input_schema, core calls the callback with zero
76	* arguments. PHP's ArgumentCountError would otherwise fatal here. Subclasses
77	* that declare a non-empty input_schema can rely on $input being a parsed
78	* array (core enforces this via rest_validate_value_from_schema()).
79	*
80	* @param mixed $input Validated input matching get_input_schema(), or null
81	* when the ability declares no input_schema.
82	* @return mixed\|\WP_Error Result conforming to get_output_schema(), or WP_Error.
83	*/
84	abstract public function execute( $input = null );
85
86	/**
87	* Permission check. Defaults to the Stream settings capability so write
88	* abilities are safe by default; read-only abilities should override with
89	* the view capability (e.g. 'view_stream') to follow least-privilege.
90	*
91	* @param array $input Input that will be passed to execute().
92	* @return bool\|\WP_Error
93	*/
94	public function permission_callback( $input = array() ) {
95	unset( $input );
96	return current_user_can( WP_STREAM_SETTINGS_CAPABILITY );
97	}
98
99	/**
100	* Annotation flags for the ability (readonly, destructive, idempotent).
101	*
102	* @return array
103	*/
104	public function get_annotations() {
105	return array();
106	}
107
108	/**
109	* Meta passed to wp_register_ability(). Sets REST exposure and (optionally) annotations.
110	*
111	* @return array
112	*/
113	public function get_meta() {
114	$meta = array(
115	'show_in_rest' => true,
116	// Mark every Stream ability as MCP-discoverable. When the
117	// WordPress MCP Adapter (wordpress/mcp-adapter) is installed,
118	// the default MCP server exposes abilities with this flag via
119	// its `mcp-adapter/discover-abilities` and `execute-ability`
120	// tools. The flag is harmless if mcp-adapter is not present
121	// (unused meta key). permission_callback still gates execution,
122	// so destructive abilities aren't auto-callable by anonymous
123	// MCP clients.
124	'mcp' => array(
125	'public' => true,
126	),
127	);
128
129	$annotations = $this->get_annotations();
130	if ( ! empty( $annotations ) ) {
131	$meta['annotations'] = $annotations;
132	}
133
134	return $meta;
135	}
136
137	/**
138	* Register the ability with the Abilities API.
139	*
140	* @return void
141	*/
142	final public function register() {
143	if ( ! function_exists( 'wp_register_ability' ) ) {
144	return;
145	}
146
147	$args = array(
148	'label' => $this->get_label(),
149	'description' => $this->get_description(),
150	'category' => Abilities::CATEGORY_SLUG,
151	'output_schema' => $this->get_output_schema(),
152	'execute_callback' => array( $this, 'execute' ),
153	'permission_callback' => array( $this, 'permission_callback' ),
154	'meta' => $this->get_meta(),
155	);
156
157	$input_schema = $this->get_input_schema();
158	if ( ! empty( $input_schema ) ) {
159	$args['input_schema'] = $input_schema;
160	}
161
162	wp_register_ability( $this->get_name(), $args );
163	}
164	}
165