WP_Connector_Registry::register() – Method

Registers a new connector.

Description

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.

Parameters

$idstringrequired

The unique connector identifier. Must match the pattern /^[a-z0-9_-]+$/ (lowercase alphanumeric, hyphens, and underscores only).

$argsarrayrequired

An associative array of arguments for the connector.

name string
Required. The connector’s display name.
description string
Optional. The connector’s description. Default empty string.
logo_url string
Optional. URL to the connector’s logo image.
type string
Required. The connector type, e.g. 'ai_provider'.
authentication array
Required. Authentication configuration.
- method string
  Required. The authentication method: 'api_key' or 'none'.
- credentials_url string
  Optional. URL where users can obtain API credentials.
- setting*name string
  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.
- constant_name string
  Optional. PHP constant name for the API key (e.g. 'ANTHROPIC_API_KEY'). Only checked when provided.
- env_var_name string
  Optional. Environment variable name for the API key (e.g. 'ANTHROPIC_API_KEY'). Only checked when provided.
plugin array
Optional. Plugin data for install/activate UI.
- file string
  Optional. The plugin’s main file path relative to the plugins directory (e.g. 'my-plugin/my-plugin.php' or 'hello.php').
- is_active callable
  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.

Source

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;
}

View all references View on Trac View on GitHub

Uses	Description
WP_Connector_Registry::is_registered()`wp-includes/class-wp-connector-registry.php`	Checks if a connector is registered.
wp_supports_ai()`wp-includes/ai-client.php`	Returns whether AI features are supported in the current environment.
__()`wp-includes/l10n.php`	Retrieves the translation of $text.
esc_html()`wp-includes/formatting.php`	Escaping for HTML blocks.
_doing_it_wrong()`wp-includes/functions.php`	Marks something as being incorrectly called.

Show 3 more Show less

Changelog

Version	Description
7.0.0	Introduced.

WP_Connector_Registry::register( string $id, array $args ): array|null

In this article

Description

See also

Parameters

Return

Source

Related

Changelog

User Contributed Notes