432 lines
14 KiB
PHP
432 lines
14 KiB
PHP
<?php
|
|
/**
|
|
* Connectors API: WP_Connector_Registry class.
|
|
*
|
|
* @package WordPress
|
|
* @subpackage Connectors
|
|
* @since 7.0.0
|
|
*/
|
|
|
|
/**
|
|
* Manages the registration and lookup of connectors.
|
|
*
|
|
* This is an internal class. Use the public API functions to interact with connectors:
|
|
*
|
|
* - `wp_is_connector_registered()` — check if a connector exists.
|
|
* - `wp_get_connector()` — retrieve a single connector's data.
|
|
* - `wp_get_connectors()` — retrieve all registered connectors.
|
|
*
|
|
* Plugins receive the registry instance via the `wp_connectors_init` action
|
|
* to register or override connectors directly.
|
|
*
|
|
* @since 7.0.0
|
|
* @access private
|
|
*
|
|
* @see wp_is_connector_registered()
|
|
* @see wp_get_connector()
|
|
* @see wp_get_connectors()
|
|
* @see _wp_connectors_init()
|
|
*
|
|
* @phpstan-type Connector array{
|
|
* name: non-empty-string,
|
|
* description: string,
|
|
* logo_url?: non-empty-string,
|
|
* type: non-empty-string,
|
|
* authentication: array{
|
|
* method: 'api_key'|'none',
|
|
* credentials_url?: non-empty-string,
|
|
* setting_name?: non-empty-string,
|
|
* constant_name?: non-empty-string,
|
|
* env_var_name?: non-empty-string
|
|
* },
|
|
* plugin: array{
|
|
* file?: non-empty-string,
|
|
* is_active: callable(): bool
|
|
* }
|
|
* }
|
|
*/
|
|
final class WP_Connector_Registry {
|
|
/**
|
|
* The singleton instance of the registry.
|
|
*
|
|
* @since 7.0.0
|
|
*/
|
|
private static ?WP_Connector_Registry $instance = null;
|
|
|
|
/**
|
|
* Holds the registered connectors.
|
|
*
|
|
* Each connector is stored as an associative array with keys:
|
|
* name, description, type, authentication, and optionally plugin.
|
|
*
|
|
* @since 7.0.0
|
|
* @var array<string, array>
|
|
* @phpstan-var array<string, Connector>
|
|
*/
|
|
private array $registered_connectors = array();
|
|
|
|
/**
|
|
* Registers a new connector.
|
|
*
|
|
* Validates the provided arguments and stores the connector in the registry.
|
|
* For connectors with `api_key` authentication, a `setting_name` can be provided
|
|
* explicitly. If omitted, one is automatically generated using the pattern
|
|
* `connectors_{$type}_{$id}_api_key`, with hyphens in the type and ID normalized
|
|
* to underscores (e.g., connector type `spam_filtering` with ID `my_plugin` produces
|
|
* `connectors_spam_filtering_my_plugin_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
|
|
*
|
|
* @see WP_Connector_Registry::unregister()
|
|
*
|
|
* @param string $id The unique connector identifier. Must match the pattern
|
|
* `/^[a-z0-9_-]+$/` (lowercase alphanumeric, hyphens, and underscores only).
|
|
* @param array $args {
|
|
* An associative array of arguments for the connector.
|
|
*
|
|
* @type string $name Required. The connector's display name.
|
|
* @type string $description Optional. The connector's description. Default empty string.
|
|
* @type string $logo_url Optional. URL to the connector's logo image.
|
|
* @type string $type Required. The connector type, e.g. 'ai_provider'.
|
|
* @type array $authentication {
|
|
* Required. Authentication configuration.
|
|
*
|
|
* @type string $method Required. The authentication method: 'api_key' or 'none'.
|
|
* @type string $credentials_url Optional. URL where users can obtain API credentials.
|
|
* @type string $setting_name Optional. The setting name for the API key.
|
|
* When omitted, auto-generated as
|
|
* `connectors_{$type}_{$id}_api_key`.
|
|
* Must be a non-empty string when provided.
|
|
* @type string $constant_name Optional. PHP constant name for the API key
|
|
* (e.g. 'ANTHROPIC_API_KEY'). Only checked when provided.
|
|
* @type string $env_var_name Optional. Environment variable name for the API key
|
|
* (e.g. 'ANTHROPIC_API_KEY'). Only checked when provided.
|
|
* }
|
|
* @type array $plugin {
|
|
* Optional. Plugin data for install/activate UI.
|
|
*
|
|
* @type string $file Optional. The plugin's main file path relative to the
|
|
* plugins directory (e.g. 'my-plugin/my-plugin.php' or
|
|
* 'hello.php').
|
|
* @type callable $is_active Optional callback to determine whether the plugin
|
|
* is active. Receives no arguments and must return bool.
|
|
* Defaults to `__return_true`.
|
|
* }
|
|
* }
|
|
* @return array|null The registered connector data on success, null on failure.
|
|
*
|
|
* @phpstan-param array{
|
|
* name: non-empty-string,
|
|
* description?: string,
|
|
* logo_url?: non-empty-string,
|
|
* type: non-empty-string,
|
|
* authentication: array{
|
|
* method: 'api_key'|'none',
|
|
* credentials_url?: non-empty-string,
|
|
* setting_name?: non-empty-string,
|
|
* constant_name?: non-empty-string,
|
|
* env_var_name?: non-empty-string
|
|
* },
|
|
* plugin?: array{
|
|
* file?: non-empty-string,
|
|
* is_active?: callable(): bool
|
|
* }
|
|
* } $args
|
|
* @phpstan-return Connector|null
|
|
*/
|
|
public function register( string $id, array $args ): ?array {
|
|
if ( ! preg_match( '/^[a-z0-9_-]+$/', $id ) ) {
|
|
_doing_it_wrong(
|
|
__METHOD__,
|
|
__(
|
|
'Connector ID must contain only lowercase alphanumeric characters, hyphens, and underscores.'
|
|
),
|
|
'7.0.0'
|
|
);
|
|
return null;
|
|
}
|
|
|
|
if ( $this->is_registered( $id ) ) {
|
|
_doing_it_wrong(
|
|
__METHOD__,
|
|
/* translators: %s: Connector ID. */
|
|
sprintf( __( 'Connector "%s" is already registered.' ), esc_html( $id ) ),
|
|
'7.0.0'
|
|
);
|
|
return null;
|
|
}
|
|
|
|
// Validate required fields.
|
|
if ( empty( $args['name'] ) || ! is_string( $args['name'] ) ) {
|
|
_doing_it_wrong(
|
|
__METHOD__,
|
|
/* translators: %s: Connector ID. */
|
|
sprintf( __( 'Connector "%s" requires a non-empty "name" string.' ), esc_html( $id ) ),
|
|
'7.0.0'
|
|
);
|
|
return null;
|
|
}
|
|
|
|
if ( empty( $args['type'] ) || ! is_string( $args['type'] ) ) {
|
|
_doing_it_wrong(
|
|
__METHOD__,
|
|
/* translators: %s: Connector ID. */
|
|
sprintf( __( 'Connector "%s" requires a non-empty "type" string.' ), esc_html( $id ) ),
|
|
'7.0.0'
|
|
);
|
|
return null;
|
|
}
|
|
|
|
if ( ! isset( $args['authentication'] ) || ! is_array( $args['authentication'] ) ) {
|
|
_doing_it_wrong(
|
|
__METHOD__,
|
|
/* translators: %s: Connector ID. */
|
|
sprintf( __( 'Connector "%s" requires an "authentication" array.' ), esc_html( $id ) ),
|
|
'7.0.0'
|
|
);
|
|
return null;
|
|
}
|
|
|
|
if ( empty( $args['authentication']['method'] ) || ! in_array( $args['authentication']['method'], array( 'api_key', 'none' ), true ) ) {
|
|
_doing_it_wrong(
|
|
__METHOD__,
|
|
/* translators: %s: Connector ID. */
|
|
sprintf( __( 'Connector "%s" authentication method must be "api_key" or "none".' ), esc_html( $id ) ),
|
|
'7.0.0'
|
|
);
|
|
return null;
|
|
}
|
|
|
|
if ( 'ai_provider' === $args['type'] && ! wp_supports_ai() ) {
|
|
// No need for a `doing_it_wrong` as AI support is disabled intentionally.
|
|
return null;
|
|
}
|
|
|
|
$connector = array(
|
|
'name' => $args['name'],
|
|
'description' => isset( $args['description'] ) && is_string( $args['description'] ) ? $args['description'] : '',
|
|
'type' => $args['type'],
|
|
'authentication' => array(
|
|
'method' => $args['authentication']['method'],
|
|
),
|
|
);
|
|
|
|
if ( ! empty( $args['logo_url'] ) && is_string( $args['logo_url'] ) ) {
|
|
$connector['logo_url'] = $args['logo_url'];
|
|
}
|
|
|
|
if ( 'api_key' === $args['authentication']['method'] ) {
|
|
if ( ! empty( $args['authentication']['credentials_url'] ) && is_string( $args['authentication']['credentials_url'] ) ) {
|
|
$connector['authentication']['credentials_url'] = $args['authentication']['credentials_url'];
|
|
}
|
|
if ( isset( $args['authentication']['setting_name'] ) ) {
|
|
if ( ! is_string( $args['authentication']['setting_name'] ) || '' === $args['authentication']['setting_name'] ) {
|
|
_doing_it_wrong(
|
|
__METHOD__,
|
|
/* translators: %s: Connector ID. */
|
|
sprintf( __( 'Connector "%s" authentication setting_name must be a non-empty string.' ), esc_html( $id ) ),
|
|
'7.0.0'
|
|
);
|
|
return null;
|
|
}
|
|
$connector['authentication']['setting_name'] = $args['authentication']['setting_name'];
|
|
} else {
|
|
$connector['authentication']['setting_name'] = str_replace( '-', '_', "connectors_{$connector['type']}_{$id}_api_key" );
|
|
}
|
|
if ( isset( $args['authentication']['constant_name'] ) ) {
|
|
if ( ! is_string( $args['authentication']['constant_name'] ) || '' === $args['authentication']['constant_name'] ) {
|
|
_doing_it_wrong(
|
|
__METHOD__,
|
|
/* translators: %s: Connector ID. */
|
|
sprintf( __( 'Connector "%s" authentication constant_name must be a non-empty string.' ), esc_html( $id ) ),
|
|
'7.0.0'
|
|
);
|
|
return null;
|
|
}
|
|
$connector['authentication']['constant_name'] = $args['authentication']['constant_name'];
|
|
}
|
|
if ( isset( $args['authentication']['env_var_name'] ) ) {
|
|
if ( ! is_string( $args['authentication']['env_var_name'] ) || '' === $args['authentication']['env_var_name'] ) {
|
|
_doing_it_wrong(
|
|
__METHOD__,
|
|
/* translators: %s: Connector ID. */
|
|
sprintf( __( 'Connector "%s" authentication env_var_name must be a non-empty string.' ), esc_html( $id ) ),
|
|
'7.0.0'
|
|
);
|
|
return null;
|
|
}
|
|
$connector['authentication']['env_var_name'] = $args['authentication']['env_var_name'];
|
|
}
|
|
}
|
|
|
|
$connector['plugin'] = array();
|
|
|
|
if ( ! empty( $args['plugin'] ) && is_array( $args['plugin'] ) ) {
|
|
if ( ! empty( $args['plugin']['file'] ) ) {
|
|
$connector['plugin']['file'] = $args['plugin']['file'];
|
|
}
|
|
|
|
if ( isset( $args['plugin']['is_active'] ) ) {
|
|
if ( ! is_callable( $args['plugin']['is_active'] ) ) {
|
|
_doing_it_wrong(
|
|
__METHOD__,
|
|
/* translators: %s: Connector ID. */
|
|
sprintf( __( 'Connector "%s" plugin is_active must be callable.' ), esc_html( $id ) ),
|
|
'7.0.0'
|
|
);
|
|
return null;
|
|
}
|
|
|
|
$connector['plugin']['is_active'] = $args['plugin']['is_active'];
|
|
}
|
|
}
|
|
|
|
if ( ! isset( $connector['plugin']['is_active'] ) ) {
|
|
$connector['plugin']['is_active'] = '__return_true';
|
|
}
|
|
|
|
$this->registered_connectors[ $id ] = $connector;
|
|
return $connector;
|
|
}
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @phpstan-return Connector|null
|
|
*/
|
|
public function unregister( string $id ): ?array {
|
|
if ( ! $this->is_registered( $id ) ) {
|
|
_doing_it_wrong(
|
|
__METHOD__,
|
|
/* translators: %s: Connector ID. */
|
|
sprintf( __( 'Connector "%s" not found.' ), esc_html( $id ) ),
|
|
'7.0.0'
|
|
);
|
|
return null;
|
|
}
|
|
|
|
$unregistered = $this->registered_connectors[ $id ];
|
|
unset( $this->registered_connectors[ $id ] );
|
|
|
|
return $unregistered;
|
|
}
|
|
|
|
/**
|
|
* Retrieves the list of all registered connectors.
|
|
*
|
|
* Do not use this method directly. Instead, use the `wp_get_connectors()` function.
|
|
*
|
|
* @since 7.0.0
|
|
*
|
|
* @see wp_get_connectors()
|
|
*
|
|
* @return array Connector settings keyed by connector ID.
|
|
*
|
|
* @phpstan-return array<string, Connector>
|
|
*/
|
|
public function get_all_registered(): array {
|
|
return $this->registered_connectors;
|
|
}
|
|
|
|
/**
|
|
* Checks if a connector is registered.
|
|
*
|
|
* Do not use this method directly. Instead, use the `wp_is_connector_registered()` function.
|
|
*
|
|
* @since 7.0.0
|
|
*
|
|
* @see wp_is_connector_registered()
|
|
*
|
|
* @param string $id The connector identifier.
|
|
* @return bool True if the connector is registered, false otherwise.
|
|
*/
|
|
public function is_registered( string $id ): bool {
|
|
return isset( $this->registered_connectors[ $id ] );
|
|
}
|
|
|
|
/**
|
|
* Retrieves a registered connector.
|
|
*
|
|
* 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()
|
|
*
|
|
* @param string $id The connector identifier.
|
|
* @return array|null The registered connector data, or null if it is not registered.
|
|
* @phpstan-return Connector|null
|
|
*/
|
|
public function get_registered( string $id ): ?array {
|
|
if ( ! $this->is_registered( $id ) ) {
|
|
_doing_it_wrong(
|
|
__METHOD__,
|
|
/* translators: %s: Connector ID. */
|
|
sprintf( __( 'Connector "%s" not found.' ), esc_html( $id ) ),
|
|
'7.0.0'
|
|
);
|
|
return null;
|
|
}
|
|
return $this->registered_connectors[ $id ];
|
|
}
|
|
|
|
/**
|
|
* Retrieves the main instance of the registry class.
|
|
*
|
|
* @since 7.0.0
|
|
*
|
|
* @return WP_Connector_Registry|null The main registry instance, or null if not yet initialized.
|
|
*/
|
|
public static function get_instance(): ?self {
|
|
return self::$instance;
|
|
}
|
|
|
|
/**
|
|
* 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 {
|
|
if ( ! doing_action( 'init' ) ) {
|
|
_doing_it_wrong(
|
|
__METHOD__,
|
|
__( 'The connector registry instance must be set during the <code>init</code> action.' ),
|
|
'7.0.0'
|
|
);
|
|
return;
|
|
}
|
|
|
|
self::$instance = $registry;
|
|
}
|
|
}
|