Connectors: Improve PHPDoc for developer documentation

[gziolo]

Trac ticket: https://core.trac.wordpress.org/ticket/64791
Follow-up for #11175

Summary

• Adds comprehensive file-level docblock to connectors.php covering overview, AI provider auto-discovery, admin UI integration, custom connectors, initialization lifecycle, and authentication.
• Documents how registry fields (plugin.slug, credentials_url, logo_url, key source) map to the Settings → Connectors admin screen.
• Adds usage examples and @see cross-references to public API functions (wp_get_connector(), wp_get_connectors(), wp_is_connector_registered()).
• Expands docblocks in WP_Connector_Registry for register(), unregister(), get_registered(), and set_instance() with behavior details, @see references, and override patterns.
• Documents _wp_connectors_get_connector_script_module_data() as the bridge between the PHP registry and the frontend admin UI.

Test plan

• Verify PHPDoc renders correctly in IDE tooltips and generated documentation.
• Confirm no functional code changes — documentation only.

🤖 Generated with Claude Code

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props gziolo.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[gziolo]

Dev Note

Introducing the Connectors API in WordPress 7.0

WordPress 7.0 introduces the Connectors API — a new framework for registering and managing connections to external services. The initial focus is on AI providers, giving WordPress a standardized way to handle API key management, provider discovery, and admin UI for configuring AI services.

This post walks through what the Connectors API does, how it works under the hood, and what plugin developers need to know.

Table of Contents

• What is a connector?
• How AI providers are auto-discovered
• The Settings > Connectors admin screen
• Authentication and API key management
• Public API functions
• Overriding connector metadata
• The initialization lifecycle
• Looking ahead

What is a connector?

A connector represents a connection to an external service. Each connector carries standardized metadata — a display name, description, logo, authentication configuration, and an optional association with a WordPress.org plugin. The system currently focuses on AI providers, but the architecture is designed to support additional connector types in future releases.

WordPress 7.0 ships with three built-in connectors: Anthropic, Google, and OpenAI. These are registered automatically during initialization and appear on the new Settings > Connectors admin screen.

Each connector is stored as an associative array with the following shape:

array(
    'name'           => 'Anthropic',
    'description'    => 'Text generation with Claude.',
    'logo_url'       => 'https://example.com/anthropic-logo.svg',
    'type'           => 'ai_provider',
    'authentication' => array(
        'method'          => 'api_key',
        'credentials_url' => 'https://platform.claude.com/settings/keys',
        'setting_name'    => 'connectors_ai_anthropic_api_key',
    ),
    'plugin'         => array(
        'slug' => 'ai-provider-for-anthropic',
    ),
)

How AI providers are auto-discovered

If you're building an AI provider plugin that integrates with the WP AI Client, you don't need to register a connector manually. The Connectors API automatically discovers providers from the WP AI Client's ProviderRegistry and creates connectors with the correct metadata.

Here's what happens during initialization:

1. Built-in connectors (Anthropic, Google, OpenAI) are registered with hardcoded defaults.
2. The system queries the WP AI Client registry for all registered providers.
3. For each provider, metadata (name, description, logo, authentication method) is merged on top of the defaults, with provider registry values taking precedence.
4. The wp_connectors_init action fires so plugins can override metadata or register additional connectors.

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 pattern connectors_ai_{$id}_api_key — the same naming convention used for environment variables and PHP constants (e.g., provider anthropic maps to ANTHROPIC_API_KEY for env/constant lookup).

In short: if your AI provider plugin registers with the WP AI Client, the connector is created for you. No additional code is needed.

The Settings > Connectors admin screen

Registered ai_provider connectors appear on a new Settings > Connectors admin screen. The screen renders each connector as a card, and the registry data drives what's displayed:

• name, description, and logo_url are shown on the card.
• plugin.slug enables install/activate controls — the screen checks whether the associated 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.

Connectors with other authentication methods or types are stored in the PHP registry and exposed via the script module data, but currently require a client-side JavaScript registration for custom frontend UI.

Authentication and API key management

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 key source priority

For api_key connectors, the system looks for a key in this order:

1. Environment variable — e.g., ANTHROPIC_API_KEY
2. PHP constant — e.g., define( 'ANTHROPIC_API_KEY', 'sk-...' );
3. Database — stored through the admin screen

The naming convention follows the pattern {PROVIDER_ID}_API_KEY in CONSTANT_CASE. For example, provider anthropic maps to ANTHROPIC_API_KEY.

Public API functions

The Connectors API provides three public functions for querying the registry. These are available after init.

wp_is_connector_registered()

Checks if a connector is registered:

if ( wp_is_connector_registered( 'anthropic' ) ) {
    // The Anthropic connector is available.
}

wp_get_connector()

Retrieves a single connector's data:

$connector = wp_get_connector( 'anthropic' );
if ( $connector ) {
    echo $connector['name']; // 'Anthropic'
}

Returns an associative array with keys: name, description, type, authentication, and optionally logo_url and plugin. Returns null if the connector is not registered.

wp_get_connectors()

Retrieves all registered connectors, keyed by connector ID:

$connectors = wp_get_connectors();
foreach ( $connectors as $id => $connector ) {
    printf( '%s: %s', $connector['name'], $connector['description'] );
}

Overriding connector metadata

The wp_connectors_init action fires after all built-in and auto-discovered connectors have been registered. Plugins can use this hook to override metadata on existing connectors.

Since the registry rejects duplicate IDs, overriding requires an unregister, modify, register sequence:

add_action( 'wp_connectors_init', function ( WP_Connector_Registry $registry ) {
    if ( $registry->is_registered( 'anthropic' ) ) {
        $connector = $registry->unregister( 'anthropic' );
        $connector['description'] = __( 'Custom description for Anthropic.', 'my-plugin' );
        $registry->register( 'anthropic', $connector );
    }
} );

Key points about the override pattern:

• Always check is_registered() before calling unregister() — calling unregister() on a non-existent connector triggers a _doing_it_wrong() notice.
• unregister() returns the connector data, which you can modify and pass back to register().
• Connector IDs must match the pattern /^[a-z0-9_]+$/ (lowercase alphanumeric and underscores only).

Registry methods

Within the wp_connectors_init callback, the WP_Connector_Registry instance provides these methods:

Method	Description
register( $id, $args )	Register a new connector. Returns the connector data or null on failure.
unregister( $id )	Remove a connector and return its data. Returns null if not found.
is_registered( $id )	Check if a connector exists.
get_registered( $id )	Retrieve a single connector's data.
get_all_registered()	Retrieve all registered connectors.

Outside of the wp_connectors_init callback, use the public API functions (wp_get_connector(), wp_get_connectors(), wp_is_connector_registered()) instead of accessing the registry directly.

The initialization lifecycle

Understanding the initialization sequence helps when deciding where to hook in:

During the init action, _wp_connectors_init() runs and:

• Creates the WP_Connector_Registry singleton.
• Registers built-in connectors (Anthropic, Google, OpenAI) with hardcoded defaults.
• Auto-discovers providers from the WP AI Client registry and merges their metadata on top of defaults.
• Fires the wp_connectors_init action — this is where plugins override metadata or register additional connectors.

The wp_connectors_init action is the only supported entry point for modifying the registry. Attempting to set the registry instance outside of init triggers a _doing_it_wrong() notice.

Looking ahead

The Connectors API in WordPress 7.0 is scoped to AI providers, but the underlying architecture is designed to grow. Currently, only ai_provider connectors with api_key authentication receive the full admin UI treatment. The PHP registry already accepts any connector type — what's missing is the frontend integration for non-AI connector types.

Future releases are expected to:

• Expand support for additional authentication methods beyond api_key and none.
• Lift the ai_provider type restriction for the admin screen.
• Provide a client-side JavaScript registration API for custom connector UI.

When those capabilities land, the wp_connectors_init action will be the primary hook for registering new connector types.

---

Props to @jorgefilipecosta, @shaunandrews, @felixarntz, @Jameswlepage, @gziolo and others for contributing to the Connectors API.

#7-0, #dev-notes