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

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

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