gutenberg / lib / compat / wordpress-7.0 / connectors.php

connectors.php in Gutenberg 23.7.2, at lib/compat/wordpress-7.0/connectors.php

242 lines 8.6 KB

Raw Download Zip

1	<?php
2	/**
3	* Connectors API functions.
4	*
5	* @package gutenberg
6	* @since 7.0.0
7	*/
8
9	if ( ! function_exists( 'wp_is_connector_registered' ) ) {
10	/**
11	* Checks if a connector is registered.
12	*
13	* @since 7.0.0
14	*
15	* @see WP_Connector_Registry::is_registered()
16	*
17	* @param string $id The connector identifier.
18	* @return bool True if the connector is registered, false otherwise.
19	*/
20	function wp_is_connector_registered( string $id ): bool {
21	$registry = WP_Connector_Registry::get_instance();
22	if ( null === $registry ) {
23	return false;
24	}
25
26	return $registry->is_registered( $id );
27	}
28	}
29
30	if ( ! function_exists( 'wp_get_connector' ) ) {
31	/**
32	* Retrieves a registered connector.
33	*
34	* @since 7.0.0
35	*
36	* @see WP_Connector_Registry::get_registered()
37	*
38	* @param string $id The connector identifier.
39	* @return array\|null {
40	* Connector data, or null if not registered.
41	*
42	* @type string $name The connector's display name.
43	* @type string $description The connector's description.
44	* @type string $logo_url Optional. URL to the connector's logo image.
45	* @type string $type The connector type, e.g. 'ai_provider' or 'spam_filtering'.
46	* @type array $authentication {
47	* Authentication configuration. When method is 'api_key' or
48	* 'application_password', includes credentials_url, setting_name, and
49	* optionally constant_name and env_var_name. When 'none', only method
50	* is present.
51	*
52	* @type string $method The authentication method: 'api_key',
53	* 'application_password', or 'none'.
54	* @type string $credentials_url Optional. URL where users can obtain API credentials.
55	* @type string $setting_name Optional. The setting name for the API key or application-password credentials.
56	* @type string $constant_name Optional. PHP constant name for the API key or application-password credentials.
57	* @type string $env_var_name Optional. Environment variable name for the API key or application-password credentials.
58	* }
59	* @type array $plugin {
60	* Optional. Plugin data for install/activate UI.
61	*
62	* @type string $file The plugin's main file path relative to the plugins
63	* directory (e.g. 'my-plugin/my-plugin.php' or 'hello.php').
64	* @type callable $is_active Callback to determine whether the plugin is active. Receives no arguments and must return bool.
65	* Defaults to `__return_true`.
66	* }
67	* }
68	* @phpstan-return ?array{
69	* name: non-empty-string,
70	* description: string,
71	* logo_url?: non-empty-string,
72	* type: non-empty-string,
73	* authentication: array{
74	* method: 'api_key'\|'application_password'\|'none',
75	* credentials_url?: non-empty-string,
76	* setting_name?: non-empty-string,
77	* constant_name?: non-empty-string,
78	* env_var_name?: non-empty-string
79	* },
80	* plugin: array{
81	* file?: non-empty-string,
82	* is_active: callable(): bool,
83	* }
84	* }
85	*/
86	function wp_get_connector( string $id ): ?array {
87	$registry = WP_Connector_Registry::get_instance();
88	if ( null === $registry ) {
89	return null;
90	}
91
92	return $registry->get_registered( $id );
93	}
94	}
95
96	if ( ! function_exists( 'wp_get_connectors' ) ) {
97	/**
98	* Retrieves all registered connectors.
99	*
100	* @since 7.0.0
101	*
102	* @see WP_Connector_Registry::get_all_registered()
103	*
104	* @return array {
105	* Connector settings keyed by connector ID.
106	*
107	* @type array ...$0 {
108	* Data for a single connector.
109	*
110	* @type string $name The connector's display name.
111	* @type string $description The connector's description.
112	* @type string $logo_url Optional. URL to the connector's logo image.
113	* @type string $type The connector type, e.g. 'ai_provider' or 'spam_filtering'.
114	* @type array $authentication {
115	* Authentication configuration. When method is 'api_key' or
116	* 'application_password', includes credentials_url, setting_name,
117	* and optionally constant_name and env_var_name. When 'none', only
118	* method is present.
119	*
120	* @type string $method The authentication method: 'api_key',
121	* 'application_password', or 'none'.
122	* @type string $credentials_url Optional. URL where users can obtain API credentials.
123	* @type string $setting_name Optional. The setting name for the API key or application-password credentials.
124	* @type string $constant_name Optional. PHP constant name for the API key or application-password credentials.
125	* @type string $env_var_name Optional. Environment variable name for the API key or application-password credentials.
126	* }
127	* @type array $plugin {
128	* Optional. Plugin data for install/activate UI.
129	*
130	* @type string $file The plugin's main file path relative to the plugins
131	* directory (e.g. 'my-plugin/my-plugin.php' or 'hello.php').
132	* @type callable $is_active Callback to determine whether the plugin is active. Receives no arguments and must return bool.
133	* Defaults to `__return_true`.
134	* }
135	* }
136	* }
137	* @phpstan-return array<string, array{
138	* name: non-empty-string,
139	* description: string,
140	* logo_url?: non-empty-string,
141	* type: non-empty-string,
142	* authentication: array{
143	* method: 'api_key'\|'application_password'\|'none',
144	* credentials_url?: non-empty-string,
145	* setting_name?: non-empty-string,
146	* constant_name?: non-empty-string,
147	* env_var_name?: non-empty-string
148	* },
149	* plugin: array{
150	* file?: non-empty-string,
151	* is_active: callable(): bool,
152	* }
153	* }>
154	*/
155	function wp_get_connectors(): array {
156	$registry = WP_Connector_Registry::get_instance();
157	if ( null === $registry ) {
158	return array();
159	}
160
161	return $registry->get_all_registered();
162	}
163	}
164
165	if ( ! function_exists( '_wp_connectors_resolve_ai_provider_logo_url' ) ) {
166	/**
167	* Resolves an AI provider logo file path to a URL.
168	*
169	* Converts an absolute file path within the plugins or must-use plugins
170	* directory to the corresponding URL.
171	*
172	* @access private
173	* @since 7.0.0
174	*
175	* @param string $path Absolute file path to the logo. Must be within
176	* WP_PLUGIN_DIR or WPMU_PLUGIN_DIR; triggers
177	* _doing_it_wrong() otherwise.
178	* @return non-empty-string\|null The logo URL, or null if the path is empty or
179	* outside the supported directories.
180	*/
181	function _wp_connectors_resolve_ai_provider_logo_url( string $path ): ?string {
182	if ( ! $path ) {
183	return null;
184	}
185
186	$path = wp_normalize_path( $path );
187
188	if ( ! file_exists( $path ) ) {
189	return null;
190	}
191
192	$mu_plugin_dir = wp_normalize_path( WPMU_PLUGIN_DIR );
193	if ( str_starts_with( $path, $mu_plugin_dir . '/' ) ) {
194	$logo_url = plugins_url( substr( $path, strlen( $mu_plugin_dir ) ), WPMU_PLUGIN_DIR . '/.' );
195	return $logo_url ? $logo_url : null;
196	}
197
198	$plugin_dir = wp_normalize_path( WP_PLUGIN_DIR );
199	if ( str_starts_with( $path, $plugin_dir . '/' ) ) {
200	$logo_url = plugins_url( substr( $path, strlen( $plugin_dir ) ) );
201	return $logo_url ? $logo_url : null;
202	}
203
204	_doing_it_wrong(
205	__FUNCTION__,
206	__( 'Provider logo path must be located within the plugins or must-use plugins directory.' ),
207	'7.0.0'
208	);
209
210	return null;
211	}
212	}
213
214	// Priority 11 to run after Core's menu.php sets up the connectors menu.
215	add_action( 'admin_menu', '_gutenberg_connectors_add_settings_menu_item', 11 );
216
217	/**
218	* Registers the Connectors menu item under Settings.
219	* Removes Core's connectors menu item first to prevent duplication.
220	*
221	* @access private
222	*/
223	function _gutenberg_connectors_add_settings_menu_item(): void {
224	if ( ! class_exists( '\WordPress\AiClient\AiClient' ) \|\| ! function_exists( 'gutenberg_options_connectors_wp_admin_render_page' ) ) {
225	return;
226	}
227
228	// Remove Core's connectors menu item if it exists.
229	remove_submenu_page( 'options-general.php', 'connectors-wp-admin' );
230	remove_submenu_page( 'options-general.php', 'options-connectors.php' );
231
232	add_submenu_page(
233	'options-general.php',
234	__( 'Connectors', 'gutenberg' ),
235	__( 'Connectors', 'gutenberg' ),
236	'manage_options',
237	'options-connectors-wp-admin',
238	'gutenberg_options_connectors_wp_admin_render_page',
239	1
240	);
241	}
242