Title: WP_Connector_Registry::register
Published: May 20, 2026

---

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

## In this article

 * [Description](https://developer.wordpress.org/reference/classes/WP_Connector_Registry/register/?output_format=md#description)
    - [See also](https://developer.wordpress.org/reference/classes/WP_Connector_Registry/register/?output_format=md#see-also)
 * [Parameters](https://developer.wordpress.org/reference/classes/WP_Connector_Registry/register/?output_format=md#parameters)
 * [Return](https://developer.wordpress.org/reference/classes/WP_Connector_Registry/register/?output_format=md#return)
 * [Source](https://developer.wordpress.org/reference/classes/WP_Connector_Registry/register/?output_format=md#source)
 * [Related](https://developer.wordpress.org/reference/classes/WP_Connector_Registry/register/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/classes/WP_Connector_Registry/register/?output_format=md#changelog)

[ Back to top](https://developer.wordpress.org/reference/classes/WP_Connector_Registry/register/?output_format=md#wp--skip-link--target)

Registers a new connector.

## 󠀁[Description](https://developer.wordpress.org/reference/classes/WP_Connector_Registry/register/?output_format=md#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.

### 󠀁[See also](https://developer.wordpress.org/reference/classes/WP_Connector_Registry/register/?output_format=md#see-also)󠁿

 * [WP_Connector_Registry::unregister()](https://developer.wordpress.org/reference/classes/WP_Connector_Registry/unregister/)

## 󠀁[Parameters](https://developer.wordpress.org/reference/classes/WP_Connector_Registry/register/?output_format=md#parameters)󠁿

 `$id`stringrequired

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

`$args`arrayrequired

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](https://developer.wordpress.org/reference/classes/WP_Connector_Registry/register/?output_format=md#return)󠁿

 array|null The registered connector data on success, null on failure.

## 󠀁[Source](https://developer.wordpress.org/reference/classes/WP_Connector_Registry/register/?output_format=md#source)󠁿

    ```php
    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](https://developer.wordpress.org/reference/files/wp-includes/class-wp-connector-registry.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/7.0/src/wp-includes/class-wp-connector-registry.php#L142)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/7.0/src/wp-includes/class-wp-connector-registry.php#L142-L295)

## 󠀁[Related](https://developer.wordpress.org/reference/classes/WP_Connector_Registry/register/?output_format=md#related)󠁿

| Uses | Description | 
| [WP_Connector_Registry::is_registered()](https://developer.wordpress.org/reference/classes/wp_connector_registry/is_registered/)`wp-includes/class-wp-connector-registry.php` |

Checks if a connector is registered.

  | 
| [wp_supports_ai()](https://developer.wordpress.org/reference/functions/wp_supports_ai/)`wp-includes/ai-client.php` |

Returns whether AI features are supported in the current environment.

  | 
| [__()](https://developer.wordpress.org/reference/functions/__/)`wp-includes/l10n.php` |

Retrieves the translation of $text.

  | 
| [esc_html()](https://developer.wordpress.org/reference/functions/esc_html/)`wp-includes/formatting.php` |

Escaping for HTML blocks.

  | 
| [_doing_it_wrong()](https://developer.wordpress.org/reference/functions/_doing_it_wrong/)`wp-includes/functions.php` |

Marks something as being incorrectly called.

  |

[Show 3 more](https://developer.wordpress.org/reference/classes/WP_Connector_Registry/register/?output_format=md#)
[Show less](https://developer.wordpress.org/reference/classes/WP_Connector_Registry/register/?output_format=md#)

## 󠀁[Changelog](https://developer.wordpress.org/reference/classes/WP_Connector_Registry/register/?output_format=md#changelog)󠁿

| Version | Description | 
| [7.0.0](https://developer.wordpress.org/reference/since/7.0.0/) | Introduced. |

## User Contributed Notes

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Fclasses%2Fwp_connector_registry%2Fregister%2F)
before being able to contribute a note or feedback.