From 6bf46b47d2a7ceee4a95d348b93446fb1941722a Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Fri, 13 Mar 2026 10:37:09 +0100 Subject: [PATCH 01/15] Connectors: Add comprehensive file-level PHPDoc overview. Add detailed documentation covering the Connectors API overview, working with connectors, initialization lifecycle, and authentication methods to improve developer discoverability and understanding. Co-Authored-By: Claude Opus 4.6 --- src/wp-includes/connectors.php | 59 +++++++++++++++++++++++++++++++++- 1 file changed, 58 insertions(+), 1 deletion(-) diff --git a/src/wp-includes/connectors.php b/src/wp-includes/connectors.php index 575f71da7766c..a2a0a976ba425 100644 --- a/src/wp-includes/connectors.php +++ b/src/wp-includes/connectors.php @@ -1,6 +1,63 @@ register( + * 'my_custom_ai', + * array( + * 'name' => __( 'My Custom AI', 'my-plugin' ), + * 'description' => __( 'Custom AI provider integration.', 'my-plugin' ), + * 'type' => 'ai_provider', + * 'authentication' => array( + * 'method' => 'api_key', + * 'credentials_url' => 'https://example.com/api-keys', + * ), + * ) + * ); + * } ); + * + * ## Initialization Lifecycle + * + * During `init`, the system: + * + * 1. Creates the `WP_Connector_Registry` singleton. + * 2. Registers built-in connectors (Anthropic, Google, OpenAI) with hardcoded defaults. + * 3. Merges metadata from the WP AI Client provider registry (name, description, + * logo, authentication) on top of defaults, with registry values taking precedence. + * 4. Fires the `wp_connectors_init` action so plugins can register additional connectors. + * 5. Registers settings and passes stored API keys to the WP AI Client. + * + * ## Authentication + * + * Connectors support two authentication methods: + * + * - `api_key`: Requires an API key, which can be provided via environment variable, + * PHP constant, or the database (checked in that order). + * - `none`: No authentication required. + * + * API keys stored in the database are automatically masked in REST API responses + * and validated against the provider on update. * * @package WordPress * @subpackage Connectors From b04567a50c2ef4e088281965bb462e32a00aeea1 Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Fri, 13 Mar 2026 10:37:49 +0100 Subject: [PATCH 02/15] Connectors: Add usage examples to public API functions. Add Example blocks to wp_is_connector_registered(), wp_get_connector(), and wp_get_connectors() to match the documentation style used in the Abilities API. Co-Authored-By: Claude Opus 4.6 --- src/wp-includes/connectors.php | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/src/wp-includes/connectors.php b/src/wp-includes/connectors.php index a2a0a976ba425..0855abf30a645 100644 --- a/src/wp-includes/connectors.php +++ b/src/wp-includes/connectors.php @@ -70,6 +70,12 @@ /** * Checks if a connector is registered. * + * Example: + * + * if ( wp_is_connector_registered( 'openai' ) ) { + * // The OpenAI connector is available. + * } + * * @since 7.0.0 * * @see WP_Connector_Registry::is_registered() @@ -89,6 +95,13 @@ function wp_is_connector_registered( string $id ): bool { /** * Retrieves a registered connector. * + * Example: + * + * $connector = wp_get_connector( 'openai' ); + * if ( $connector ) { + * echo $connector['name']; // 'OpenAI' + * } + * * @since 7.0.0 * * @see WP_Connector_Registry::get_registered() @@ -142,6 +155,13 @@ function wp_get_connector( string $id ): ?array { /** * Retrieves all registered connectors. * + * Example: + * + * $connectors = wp_get_connectors(); + * foreach ( $connectors as $id => $connector ) { + * printf( '%s: %s', $connector['name'], $connector['description'] ); + * } + * * @since 7.0.0 * * @see WP_Connector_Registry::get_all_registered() From fa6b3541daee69dab08e2d48d328a795c7259e91 Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Fri, 13 Mar 2026 10:40:58 +0100 Subject: [PATCH 03/15] Connectors: Add @see cross-references to public API functions. Add consistent @see tags linking related public functions (wp_is_connector_registered, wp_get_connector, wp_get_connectors) to each other, improving navigability for developers. Co-Authored-By: Claude Opus 4.6 --- src/wp-includes/connectors.php | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/wp-includes/connectors.php b/src/wp-includes/connectors.php index 0855abf30a645..6139eddbd121f 100644 --- a/src/wp-includes/connectors.php +++ b/src/wp-includes/connectors.php @@ -79,6 +79,8 @@ * @since 7.0.0 * * @see WP_Connector_Registry::is_registered() + * @see wp_get_connector() + * @see wp_get_connectors() * * @param string $id The connector identifier. * @return bool True if the connector is registered, false otherwise. @@ -105,6 +107,8 @@ function wp_is_connector_registered( string $id ): bool { * @since 7.0.0 * * @see WP_Connector_Registry::get_registered() + * @see wp_is_connector_registered() + * @see wp_get_connectors() * * @param string $id The connector identifier. * @return array|null { @@ -165,6 +169,8 @@ function wp_get_connector( string $id ): ?array { * @since 7.0.0 * * @see WP_Connector_Registry::get_all_registered() + * @see wp_is_connector_registered() + * @see wp_get_connector() * * @return array { * Connector settings keyed by connector ID. From 2d8c9c113f3538ee09eb9041c32c56450646f3e6 Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Fri, 13 Mar 2026 10:43:15 +0100 Subject: [PATCH 04/15] Connectors: Expand _wp_connectors_init() docblock with initialization sequence. Document the full initialization lifecycle including registry creation, built-in connector defaults, AI Client metadata merging, and the wp_connectors_init action firing order. Co-Authored-By: Claude Opus 4.6 --- src/wp-includes/connectors.php | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/src/wp-includes/connectors.php b/src/wp-includes/connectors.php index 6139eddbd121f..6659d954b3f41 100644 --- a/src/wp-includes/connectors.php +++ b/src/wp-includes/connectors.php @@ -266,8 +266,20 @@ function _wp_connectors_resolve_ai_provider_logo_url( string $path ): ?string { /** * Initializes the connector registry with default connectors and fires the registration action. * - * Creates the registry instance, registers built-in connectors (which cannot be unhooked), - * and then fires the `wp_connectors_init` action for plugins to register their own connectors. + * This function orchestrates the full connector initialization sequence: + * + * 1. Creates the `WP_Connector_Registry` singleton instance. + * 2. Defines built-in connectors (Anthropic, Google, OpenAI) with hardcoded defaults + * including name, description, type, plugin slug, and authentication configuration. + * 3. Merges metadata from the WP AI Client provider registry on top of defaults. + * Registry values (from provider plugins) take precedence over hardcoded fallbacks + * for name, description, logo URL, and authentication method. + * 4. Registers all connectors (built-in and AI Client-discovered) on the registry. + * 5. Fires the `wp_connectors_init` action for plugins to register additional connectors. + * + * Built-in connectors are registered before the action fires and cannot be unhooked. + * Plugins should use the `wp_connectors_init` action to add their own connectors + * via `$registry->register()`. * * @since 7.0.0 * @access private From d363c3cfea1dbc2564c8d067898ebf489365fc50 Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Fri, 13 Mar 2026 11:00:46 +0100 Subject: [PATCH 05/15] Connectors: Clarify AI provider auto-discovery and admin UI scope in PHPDoc. Document that AI provider plugins registered with the WP AI Client get automatic connector integration without explicit registration. Add new sections covering admin UI integration scope (ai_provider + api_key only), the auto-generated setting_name convention, and that other configurations require client-side JS for frontend UI with plans to extend support. Co-Authored-By: Claude Opus 4.6 --- src/wp-includes/connectors.php | 54 +++++++++++++++++++++++++++++----- 1 file changed, 46 insertions(+), 8 deletions(-) diff --git a/src/wp-includes/connectors.php b/src/wp-includes/connectors.php index 6659d954b3f41..8006c6c2f013a 100644 --- a/src/wp-includes/connectors.php +++ b/src/wp-includes/connectors.php @@ -16,11 +16,41 @@ * - Associate connectors with WordPress.org plugins for install/activate UI. * - Expose connector settings through the REST API with automatic key masking. * - * ## Working with Connectors + * ## AI Provider Plugins * - * Connectors are registered via the `wp_connectors_init` action hook. WordPress - * registers built-in connectors (Anthropic, Google, OpenAI) before this action - * fires, and plugins can add their own within the hook: + * AI provider plugins that register with the WP AI Client get automatic connector + * integration — no explicit connector registration is needed. The system discovers + * providers from the WP AI Client registry and creates connectors with the correct + * name, description, logo, authentication method, and setting name derived from + * the provider's configuration. + * + * The authentication method (`api_key` or `none`) is determined by the provider's + * metadata in the WP AI Client. For `api_key` providers, a `setting_name` is + * automatically generated following the same naming convention used for environment + * variables and PHP constants (e.g., provider `openai` maps to `OPENAI_API_KEY` + * for env/constant lookup). + * + * ## Admin UI Integration + * + * Connectors of type `ai_provider` with authentication method `api_key` receive + * full admin UI integration out of the box: + * + * - Automatic settings registration via the Settings API (`show_in_rest`). + * - API key masking in REST API responses (raw keys are never exposed). + * - Key validation against the provider on update. + * - Key source detection (environment variable, PHP constant, or database). + * - Frontend settings UI in the Connectors admin screen. + * + * Connectors with other authentication methods or types are registered in the PHP + * registry and exposed via the script module data, but require a client-side + * JavaScript registration for custom frontend UI. Support for additional + * authentication methods and connector types is planned for future releases. + * + * ## Custom Connectors + * + * Plugins can register additional connectors via the `wp_connectors_init` action + * hook. This is intended for non-AI-provider connectors or for overriding metadata + * on existing ones: * * add_action( 'wp_connectors_init', function ( WP_Connector_Registry $registry ) { * $registry->register( @@ -43,8 +73,9 @@ * * 1. Creates the `WP_Connector_Registry` singleton. * 2. Registers built-in connectors (Anthropic, Google, OpenAI) with hardcoded defaults. - * 3. Merges metadata from the WP AI Client provider registry (name, description, - * logo, authentication) on top of defaults, with registry values taking precedence. + * 3. Auto-discovers providers from the WP AI Client registry and merges their + * metadata (name, description, logo, authentication) on top of defaults, + * with registry values taking precedence. * 4. Fires the `wp_connectors_init` action so plugins can register additional connectors. * 5. Registers settings and passes stored API keys to the WP AI Client. * @@ -389,8 +420,15 @@ function _wp_connectors_init(): void { /** * Fires when the connector registry is ready for plugins to register connectors. * - * Default connectors have already been registered at this point and cannot be - * unhooked. Use `$registry->register()` within this action to add new connectors. + * Built-in connectors and any AI providers auto-discovered from the WP AI Client + * registry have already been registered at this point and cannot be unhooked. + * + * AI provider plugins that register with the WP AI Client do not need to use + * this action — their connectors are created automatically. This action is + * primarily for registering non-AI-provider connectors or overriding metadata + * on existing connectors. + * + * Use `$registry->register()` within this action to add new connectors. * * Example usage: * From b9c8ca594fdd4c6164b747950becd08ebf7d1f63 Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Fri, 13 Mar 2026 11:03:59 +0100 Subject: [PATCH 06/15] Connectors: Replace misleading ai_provider examples with metadata override. The previous examples showed registering a new ai_provider connector manually, which contradicts the auto-discovery model. Replace with examples showing the realistic use case: overriding metadata on an existing auto-discovered connector. Add forward-looking note about future connector types. Co-Authored-By: Claude Opus 4.6 --- src/wp-includes/connectors.php | 52 +++++++++++++++------------------- 1 file changed, 23 insertions(+), 29 deletions(-) diff --git a/src/wp-includes/connectors.php b/src/wp-includes/connectors.php index 8006c6c2f013a..214985bc5c961 100644 --- a/src/wp-includes/connectors.php +++ b/src/wp-includes/connectors.php @@ -48,25 +48,25 @@ * * ## Custom Connectors * - * Plugins can register additional connectors via the `wp_connectors_init` action - * hook. This is intended for non-AI-provider connectors or for overriding metadata - * on existing ones: + * Plugins can use the `wp_connectors_init` action hook to override metadata on + * existing connectors or register new connector types. AI provider connectors + * are auto-discovered from the WP AI Client registry and should not be manually + * registered here. + * + * Example — overriding the description of an auto-discovered connector: * * add_action( 'wp_connectors_init', function ( WP_Connector_Registry $registry ) { - * $registry->register( - * 'my_custom_ai', - * array( - * 'name' => __( 'My Custom AI', 'my-plugin' ), - * 'description' => __( 'Custom AI provider integration.', 'my-plugin' ), - * 'type' => 'ai_provider', - * 'authentication' => array( - * 'method' => 'api_key', - * 'credentials_url' => 'https://example.com/api-keys', - * ), - * ) - * ); + * $connector = $registry->get_registered( 'openai' ); + * if ( $connector ) { + * $connector['description'] = __( 'Custom description for OpenAI.', 'my-plugin' ); + * $registry->register( 'openai', $connector ); + * } * } ); * + * As the Connectors API evolves to support additional connector types beyond + * `ai_provider`, this action will also be the primary hook for registering + * those new connector types. + * * ## Initialization Lifecycle * * During `init`, the system: @@ -428,23 +428,17 @@ function _wp_connectors_init(): void { * primarily for registering non-AI-provider connectors or overriding metadata * on existing connectors. * - * Use `$registry->register()` within this action to add new connectors. + * Use `$registry->register()` within this action to add new connectors or + * re-register existing ones with updated metadata. * - * Example usage: + * Example — overriding metadata on an auto-discovered connector: * * add_action( 'wp_connectors_init', function ( WP_Connector_Registry $registry ) { - * $registry->register( - * 'my_custom_ai', - * array( - * 'name' => __( 'My Custom AI', 'my-plugin' ), - * 'description' => __( 'Custom AI provider integration.', 'my-plugin' ), - * 'type' => 'ai_provider', - * 'authentication' => array( - * 'method' => 'api_key', - * 'credentials_url' => 'https://example.com/api-keys', - * ), - * ) - * ); + * $connector = $registry->get_registered( 'openai' ); + * if ( $connector ) { + * $connector['description'] = __( 'Custom description for OpenAI.', 'my-plugin' ); + * $registry->register( 'openai', $connector ); + * } * } ); * * @since 7.0.0 From d9e0ed737d5c1d97b4bc16cd1017493c56047344 Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Fri, 13 Mar 2026 11:08:48 +0100 Subject: [PATCH 07/15] Connectors: Fix override examples to use unregister/register pattern. The registry rejects duplicate IDs with _doing_it_wrong(), so overriding an existing connector requires unregistering first. Guard with is_registered() to avoid warnings when the connector is absent, then use unregister() return value to get the data, modify, and re-register. Co-Authored-By: Claude Opus 4.6 --- src/wp-includes/connectors.php | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/src/wp-includes/connectors.php b/src/wp-includes/connectors.php index 214985bc5c961..92a72f071decd 100644 --- a/src/wp-includes/connectors.php +++ b/src/wp-includes/connectors.php @@ -56,8 +56,8 @@ * Example — overriding the description of an auto-discovered connector: * * add_action( 'wp_connectors_init', function ( WP_Connector_Registry $registry ) { - * $connector = $registry->get_registered( 'openai' ); - * if ( $connector ) { + * if ( $registry->is_registered( 'openai' ) ) { + * $connector = $registry->unregister( 'openai' ); * $connector['description'] = __( 'Custom description for OpenAI.', 'my-plugin' ); * $registry->register( 'openai', $connector ); * } @@ -428,14 +428,15 @@ function _wp_connectors_init(): void { * primarily for registering non-AI-provider connectors or overriding metadata * on existing connectors. * - * Use `$registry->register()` within this action to add new connectors or - * re-register existing ones with updated metadata. + * Use `$registry->register()` within this action to add new connectors. + * To override an existing connector, unregister it first, then re-register + * with updated data. * * Example — overriding metadata on an auto-discovered connector: * * add_action( 'wp_connectors_init', function ( WP_Connector_Registry $registry ) { - * $connector = $registry->get_registered( 'openai' ); - * if ( $connector ) { + * if ( $registry->is_registered( 'openai' ) ) { + * $connector = $registry->unregister( 'openai' ); * $connector['description'] = __( 'Custom description for OpenAI.', 'my-plugin' ); * $registry->register( 'openai', $connector ); * } From afd6efcb70cb9b2cc3b86800454c709295bf294e Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Fri, 13 Mar 2026 11:15:03 +0100 Subject: [PATCH 08/15] Connectors: Add ProviderRegistry pointer and clarify non-AI connector limitations. Add @see reference to WordPress\AiClient\Providers\ProviderRegistry so developers know where to start for AI provider integration. Rework the Custom Connectors section to explicitly state that non-AI-provider connector types are not yet fully supported and only ai_provider with api_key auth receives automatic admin UI. Co-Authored-By: Claude Opus 4.6 --- src/wp-includes/connectors.php | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/src/wp-includes/connectors.php b/src/wp-includes/connectors.php index 92a72f071decd..c72c6199238f3 100644 --- a/src/wp-includes/connectors.php +++ b/src/wp-includes/connectors.php @@ -18,11 +18,11 @@ * * ## AI Provider Plugins * - * AI provider plugins that register with the WP AI Client get automatic connector - * integration — no explicit connector registration is needed. The system discovers - * providers from the WP AI Client registry and creates connectors with the correct - * name, description, logo, authentication method, and setting name derived from - * the provider's configuration. + * AI provider plugins that register with the WP AI Client's `ProviderRegistry` + * get automatic connector integration — no explicit connector registration is + * needed. The system discovers providers from the WP AI Client registry and + * creates connectors with the correct name, description, logo, authentication + * method, and setting name derived from the provider's configuration. * * The authentication method (`api_key` or `none`) is determined by the provider's * metadata in the WP AI Client. For `api_key` providers, a `setting_name` is @@ -30,6 +30,8 @@ * variables and PHP constants (e.g., provider `openai` maps to `OPENAI_API_KEY` * for env/constant lookup). * + * @see WordPress\AiClient\Providers\ProviderRegistry + * * ## Admin UI Integration * * Connectors of type `ai_provider` with authentication method `api_key` receive @@ -48,10 +50,9 @@ * * ## Custom Connectors * - * Plugins can use the `wp_connectors_init` action hook to override metadata on - * existing connectors or register new connector types. AI provider connectors - * are auto-discovered from the WP AI Client registry and should not be manually - * registered here. + * The `wp_connectors_init` action hook allows plugins to override metadata on + * existing connectors. AI provider connectors are auto-discovered from the WP + * AI Client registry and should not be manually registered here. * * Example — overriding the description of an auto-discovered connector: * @@ -63,9 +64,12 @@ * } * } ); * - * As the Connectors API evolves to support additional connector types beyond - * `ai_provider`, this action will also be the primary hook for registering - * those new connector types. + * Non-AI-provider connector types are not yet fully supported. The PHP registry + * accepts any connector type, but only `ai_provider` connectors with `api_key` + * authentication receive automatic admin UI. Support for additional connector + * types with dedicated frontend integration is planned for future releases. + * When available, this action will be the primary hook for registering those + * new connector types. * * ## Initialization Lifecycle * From 26018f6acdc89611706c084f2c44dfd42d0c3baa Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Fri, 13 Mar 2026 11:26:43 +0100 Subject: [PATCH 09/15] Connectors: Improve file-level and class-level docblocks for WP_Connector_Registry. Add public API function references and @see tags to guide developers toward the correct entry points. Clarify that this is an internal class and plugins interact via wp_connectors_init action. Co-Authored-By: Claude Opus 4.6 --- .../class-wp-connector-registry.php | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/src/wp-includes/class-wp-connector-registry.php b/src/wp-includes/class-wp-connector-registry.php index 855d93c803c89..5dadcde80608f 100644 --- a/src/wp-includes/class-wp-connector-registry.php +++ b/src/wp-includes/class-wp-connector-registry.php @@ -1,8 +1,6 @@ Date: Fri, 13 Mar 2026 11:27:48 +0100 Subject: [PATCH 10/15] Connectors: Document setting_name auto-generation and duplicate ID behavior in register(). Explain that api_key connectors get an auto-generated setting_name using the pattern connectors_ai_{id}_api_key. Document that duplicate IDs are rejected with _doing_it_wrong() and add @see to unregister(). Co-Authored-By: Claude Opus 4.6 --- src/wp-includes/class-wp-connector-registry.php | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/src/wp-includes/class-wp-connector-registry.php b/src/wp-includes/class-wp-connector-registry.php index 5dadcde80608f..9d030f922de3c 100644 --- a/src/wp-includes/class-wp-connector-registry.php +++ b/src/wp-includes/class-wp-connector-registry.php @@ -65,10 +65,22 @@ final class WP_Connector_Registry { /** * Registers a new connector. * + * Validates the provided arguments and stores the connector in the registry. + * For connectors with `api_key` authentication, a `setting_name` is automatically + * generated using the pattern `connectors_ai_{$id}_api_key` (e.g., connector ID + * `openai` produces `connectors_ai_openai_api_key`). This setting name is used + * for the Settings API registration and REST API exposure. + * + * Registering a connector with an ID that is already registered will trigger a + * `_doing_it_wrong()` notice and return `null`. To override an existing connector, + * call `unregister()` first. + * * @since 7.0.0 * - * @param string $id The unique connector identifier. Must contain only lowercase - * alphanumeric characters and underscores. + * @see WP_Connector_Registry::unregister() + * + * @param string $id The unique connector identifier. Must match the pattern + * `/^[a-z0-9_]+$/` (lowercase alphanumeric and underscores only). * @param array $args { * An associative array of arguments for the connector. * From 9af44e78f28de4f1c570b9ef3996d4d67a7ff759 Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Fri, 13 Mar 2026 11:28:19 +0100 Subject: [PATCH 11/15] Connectors: Improve unregister() docblock with override pattern and @see references. Document that unregister() returns connector data for the override pattern, warn about _doing_it_wrong() on missing IDs, and add @see to register() and is_registered(). Co-Authored-By: Claude Opus 4.6 --- src/wp-includes/class-wp-connector-registry.php | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/wp-includes/class-wp-connector-registry.php b/src/wp-includes/class-wp-connector-registry.php index 9d030f922de3c..ea42e022cb7dd 100644 --- a/src/wp-includes/class-wp-connector-registry.php +++ b/src/wp-includes/class-wp-connector-registry.php @@ -199,8 +199,17 @@ public function register( string $id, array $args ): ?array { /** * Unregisters a connector. * + * Returns the connector data on success, which can be modified and passed + * back to `register()` to override a connector's metadata. + * + * Triggers a `_doing_it_wrong()` notice if the connector is not registered. + * Use `is_registered()` to check first when the connector may not exist. + * * @since 7.0.0 * + * @see WP_Connector_Registry::register() + * @see WP_Connector_Registry::is_registered() + * * @param string $id The connector identifier. * @return array|null The unregistered connector data on success, null on failure. * From a7557368c0f7243453055bfdc27bffe638d5a97d Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Fri, 13 Mar 2026 11:28:40 +0100 Subject: [PATCH 12/15] Connectors: Document _doing_it_wrong() behavior on get_registered(). Warn developers that calling get_registered() with an unregistered ID triggers a _doing_it_wrong() notice, and suggest using is_registered() to check first. Co-Authored-By: Claude Opus 4.6 --- src/wp-includes/class-wp-connector-registry.php | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/wp-includes/class-wp-connector-registry.php b/src/wp-includes/class-wp-connector-registry.php index ea42e022cb7dd..f76867bab0746 100644 --- a/src/wp-includes/class-wp-connector-registry.php +++ b/src/wp-includes/class-wp-connector-registry.php @@ -270,6 +270,9 @@ public function is_registered( string $id ): bool { * * Do not use this method directly. Instead, use the `wp_get_connector()` function. * + * Triggers a `_doing_it_wrong()` notice if the connector is not registered. + * Use `is_registered()` to check first when the connector may not exist. + * * @since 7.0.0 * * @see wp_get_connector() From 622eb0f32f91011cab1923da720f03a20617e1b0 Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Fri, 13 Mar 2026 11:29:02 +0100 Subject: [PATCH 13/15] Connectors: Add context and @see to set_instance() docblock. Clarify that set_instance() is called by _wp_connectors_init() during init and must not be called outside of that context. Co-Authored-By: Claude Opus 4.6 --- src/wp-includes/class-wp-connector-registry.php | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/wp-includes/class-wp-connector-registry.php b/src/wp-includes/class-wp-connector-registry.php index f76867bab0746..4f4c95014ff76 100644 --- a/src/wp-includes/class-wp-connector-registry.php +++ b/src/wp-includes/class-wp-connector-registry.php @@ -308,9 +308,14 @@ public static function get_instance(): ?self { /** * Sets the main instance of the registry class. * + * Called by `_wp_connectors_init()` during the `init` action. Must not be + * called outside of that context. + * * @since 7.0.0 * @access private * + * @see _wp_connectors_init() + * * @param WP_Connector_Registry $registry The registry instance. */ public static function set_instance( WP_Connector_Registry $registry ): void { From 45a5c7858218cd9952c710e4f105dc82cffc8447 Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Fri, 13 Mar 2026 11:51:22 +0100 Subject: [PATCH 14/15] Docs: Document how connector registry data maps to the admin screen UI. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Expands the "Admin UI Integration" section in the file-level docblock to explain what the Settings → Connectors screen renders for each registry field (name, logo, plugin install/activate, credentials URL, key source). Also enriches the `_wp_connectors_get_connector_script_module_data()` docblock to describe its role bridging the PHP registry and the frontend. Co-Authored-By: Claude Opus 4.6 --- src/wp-includes/connectors.php | 42 ++++++++++++++++++++++++++-------- 1 file changed, 32 insertions(+), 10 deletions(-) diff --git a/src/wp-includes/connectors.php b/src/wp-includes/connectors.php index c72c6199238f3..fc54fd7a19fd4 100644 --- a/src/wp-includes/connectors.php +++ b/src/wp-includes/connectors.php @@ -34,14 +34,22 @@ * * ## Admin UI Integration * - * Connectors of type `ai_provider` with authentication method `api_key` receive - * full admin UI integration out of the box: - * - * - Automatic settings registration via the Settings API (`show_in_rest`). - * - API key masking in REST API responses (raw keys are never exposed). - * - Key validation against the provider on update. - * - Key source detection (environment variable, PHP constant, or database). - * - Frontend settings UI in the Connectors admin screen. + * Registered `ai_provider` connectors appear on the Settings → Connectors + * admin screen. The screen renders each connector as a card using the + * registry data: + * + * - `name`, `description`, and `logo_url` are displayed on the card. + * - `plugin.slug` enables install/activate controls — the screen checks + * whether the plugin is installed and active, and shows the appropriate + * action button. + * - `authentication.credentials_url` is rendered as a link directing users + * to the provider's site to obtain API credentials. + * - For `api_key` connectors, the screen shows the current key source + * (environment variable, PHP constant, or database) and connection status. + * + * On the backend, `api_key` connectors also receive automatic settings + * registration via the Settings API (`show_in_rest`), API key masking in + * REST API responses, and key validation against the provider on update. * * Connectors with other authentication methods or types are registered in the PHP * registry and exposed via the script module data, but require a client-side @@ -705,13 +713,27 @@ function _wp_connectors_pass_default_keys_to_ai_client(): void { add_action( 'init', '_wp_connectors_pass_default_keys_to_ai_client', 20 ); /** - * Exposes connector settings to the connectors-wp-admin script module. + * Provides connector data to the Settings → Connectors admin screen. + * + * This function is the bridge between the PHP connector registry and the + * frontend admin UI. It transforms each registered connector into the data + * structure consumed by the `options-connectors-wp-admin` script module, + * enriching registry data with runtime state: + * + * - Plugin install/activate status (via `get_plugins()` and `is_plugin_active()`). + * - API key source detection (`env`, `constant`, `database`, or `none`). + * - Connection status for `api_key` connectors (via the WP AI Client registry). + * + * Hooked to the `script_module_data_options-connectors-wp-admin` filter. * * @since 7.0.0 * @access private * + * @see _wp_connectors_get_api_key_source() + * * @param array $data Existing script module data. - * @return array Script module data with connectors added. + * @return array Script module data with a `connectors` key added, + * keyed by connector ID and sorted alphabetically. */ function _wp_connectors_get_connector_script_module_data( array $data ): array { $registry = AiClient::defaultRegistry(); From a4f5009fb4f472e3235db3ec7372c1aebace0fb3 Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Fri, 13 Mar 2026 11:56:03 +0100 Subject: [PATCH 15/15] Docs: Fix consistency in connectors.php docblocks. Aligns Overview, Initialization Lifecycle, and _wp_connectors_init() to reflect that the wp_connectors_init action is primarily for overriding metadata on existing connectors, not just registering new ones. Expands _wp_register_default_connector_settings() to document its scope. Co-Authored-By: Claude Opus 4.6 --- src/wp-includes/connectors.php | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/src/wp-includes/connectors.php b/src/wp-includes/connectors.php index fc54fd7a19fd4..dbf44a0a1ffd6 100644 --- a/src/wp-includes/connectors.php +++ b/src/wp-includes/connectors.php @@ -11,7 +11,7 @@ * * The Connectors API enables developers to: * - * - Register custom connectors with standardized interfaces. + * - Register AI provider connectors with standardized interfaces. * - Define authentication methods and credential sources. * - Associate connectors with WordPress.org plugins for install/activate UI. * - Expose connector settings through the REST API with automatic key masking. @@ -88,7 +88,8 @@ * 3. Auto-discovers providers from the WP AI Client registry and merges their * metadata (name, description, logo, authentication) on top of defaults, * with registry values taking precedence. - * 4. Fires the `wp_connectors_init` action so plugins can register additional connectors. + * 4. Fires the `wp_connectors_init` action so plugins can override metadata + * on existing connectors or register additional connectors. * 5. Registers settings and passes stored API keys to the WP AI Client. * * ## Authentication @@ -318,11 +319,12 @@ function _wp_connectors_resolve_ai_provider_logo_url( string $path ): ?string { * Registry values (from provider plugins) take precedence over hardcoded fallbacks * for name, description, logo URL, and authentication method. * 4. Registers all connectors (built-in and AI Client-discovered) on the registry. - * 5. Fires the `wp_connectors_init` action for plugins to register additional connectors. + * 5. Fires the `wp_connectors_init` action for plugins to override metadata + * on existing connectors or register additional connectors. * * Built-in connectors are registered before the action fires and cannot be unhooked. - * Plugins should use the `wp_connectors_init` action to add their own connectors - * via `$registry->register()`. + * Plugins should use the `wp_connectors_init` action to override metadata or + * register new connectors via `$registry->register()`. * * @since 7.0.0 * @access private @@ -626,6 +628,11 @@ function _wp_connectors_rest_settings_dispatch( WP_REST_Response $response, WP_R /** * Registers default connector settings. * + * Only registers settings for `ai_provider` connectors with `api_key` + * authentication whose provider is present in the WP AI Client registry. + * Each setting is registered with `show_in_rest` enabled, making it + * accessible through the `/wp/v2/settings` REST endpoint. + * * @since 7.0.0 * @access private */