Introdução à Connectors API no WordPress 7.0

O WordPress 7.0 introduz a Connectors API (API de Conectores) — uma nova estrutura (framework) para registrar e gerenciar conexões com serviços externos. O foco inicial está nos provedores de Inteligência Artificial, fornecendo ao WordPress uma forma padronizada de gerenciar chaves de API, descobrir provedores e oferecer uma interface de usuário (UI) administrativa para configurar serviços de IA.

Este post detalha o que a Connectors API faz, como ela funciona por baixo dos panos e o que os desenvolvedores de plugins precisam saber.

O que é um conector?

Um conector representa uma conexão com um serviço externo. Cada conector carrega metadados padronizados — nome de exibição, descrição, logotipo, configuração de autenticação e uma associação opcional a um plugin do WordPress.org. O sistema atualmente foca em provedores que se autenticam por meio de uma chave de API, mas a arquitetura foi projetada para suportar tipos adicionais de conectores em versões futuras.

O WordPress 7.0 vem com três conectores nativos (em destaque) — Anthropic, Google e OpenAI — acessíveis a partir da nova tela em Configurações → Conectores, o que torna a instalação fácil e contínua.

Cada conector é armazenado como um array associativo com o seguinte formato:

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(
        'file' => 'ai-provider-for-anthropic/plugin.php',
    ),
)

Como provedores de IA são descobertos automaticamente

Se você está construindo um plugin de provedor de IA que se integra ao WP AI Client, não precisa registrar um conector manualmente. A Connectors API descobre automaticamente os provedores por meio do registro (registry) padrão do WP AI Client e cria os conectores com os metadados corretos.

Aqui está o que acontece durante a inicialização:

1. Os conectores nativos (Anthropic, Google, OpenAI) são registrados com padrões definidos diretamente no código (hardcoded defaults).
2. O sistema consulta o AiClient::defaultRegistry() em busca de todos os provedores registrados.
3. Para cada provedor, os metadados (nome, descrição, logo, método de autenticação) são mesclados por cima dos padrões, de forma que os valores vindos do registro do provedor assumam a precedência.
4. A action wp_connectors_init é disparada para que os plugins possam sobrescrever metadados ou registrar conectores adicionais.

Em resumo: se o seu plugin de provedor de IA for registrado no WP AI Client, o conector será criado para você automaticamente e nenhum código adicional será necessário.

A tela de administração Configurações > Conectores

Os conectores registrados aparecem em uma nova tela de administração, localizada em Configurações > Conectores. A tela renderiza cada conector como um cartão (card), e os dados do registro definem o que é exibido nela:

• name, description e logo_url são mostrados no cartão.
• plugin.file — o valor corresponde ao caminho principal do arquivo do plugin em relação ao diretório de plugins (por exemplo, akismet/akismet.php ou hello.php). A tela utiliza essa informação para verificar se o plugin associado está instalado e ativo, exibindo o botão de ação correspondente.
• authentication.credentials_url é renderizado como um link que direciona os usuários ao site do provedor para a obtenção das credenciais da API.
• Para conectores do tipo api_key, a tela mostra a fonte atual da chave (variável de ambiente, constante PHP ou banco de dados) e o seu status de conexão.

Conectores com outros métodos de autenticação são armazenados no registro do PHP e expostos por meio dos dados do módulo de script (script module), mas, atualmente, exigem um registro de JavaScript do lado do cliente (client-side) caso você queira uma interface personalizada no frontend.

Autenticação e gerenciamento de chaves de API

Os conectores suportam dois métodos de autenticação:

• api_key — Exige uma chave de API, que pode ser fornecida via variável de ambiente, constante PHP ou armazenada no banco de dados (nesta ordem de verificação).
• none — Nenhuma autenticação é necessária.

O método de autenticação (api_key ou none) é determinado pelos metadados de autenticação do registro do conector. Para provedores usando api_key, um nome de opção (setting) para o banco de dados é gerado automaticamente utilizando o padrão connectors_{$provider_type}_{$provider_id}_api_key. Também é possível definir um nome personalizado usando a propriedade setting_name. As chaves de API salvas no banco de dados não são encriptadas, mas ficam mascaradas e ocultas na interface de usuário. A adição de criptografia está sendo explorada em um ticket de acompanhamento: #64789.

Para provedores de IA, existe uma convenção de nomenclatura específica para variáveis de ambiente e constantes PHP: {PROVIDER_ID}_API_KEY (por exemplo, o provedor da anthropic seria mapeado para ANTHROPIC_API_KEY). Para outros tipos de provedores, pode-se, de modo opcional, definir uma variável de ambiente (env_var_name) e uma constante PHP (constant_name) com qualquer valor.

Prioridade de origem da chave de API
Para conectores api_key, o sistema busca o valor da configuração exatamente nesta ordem:

1. Variável de ambiente — ex.: ANTHROPIC_API_KEY
2. Constante PHP — ex.: define( 'ANTHROPIC_API_KEY', 'sk-...' );
3. Banco de dados — salvo através da tela de administração, ex.: a opção connectors_ai_anthropic_api_key.

Funções públicas da API

A Connectors API fornece três funções públicas para interagir com o registro. Elas ficam disponíveis após a ação init.

wp_is_connector_registered()
Verifica se um conector está registrado:

if ( wp_is_connector_registered( 'anthropic' ) ) {
    // O conector da Anthropic está disponível.
}

wp_get_connector()
Recupera os dados de um único conector:

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

Retorna um array associativo contendo as chaves: name, description, type, authentication e, opcionalmente, logo_url e plugin. Retorna null caso o conector não esteja registrado.

wp_get_connectors()
Recupera todos os conectores registrados, sendo as chaves (keys) os respectivos IDs de cada conector:

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

Sobrescrevendo metadados do conector

A action wp_connectors_init é disparada após o registro de todos os conectores nativos e autodescobertos. Os plugins podem usar este hook para sobrescrever os metadados dos conectores existentes.

Considerando que o registry (registro) rejeita IDs duplicados, para realizar uma sobrescrita é necessário efetuar uma sequência de remoção (unregister), modificação e um novo registro (register):

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

Pontos importantes sobre o padrão de sobrescrita:

• Sempre verifique utilizando is_registered() antes de chamar unregister() — invocar unregister() num conector que não existe irá disparar um aviso _doing_it_wrong().
• unregister() retorna os dados do conector, os quais você pode então modificar e repassar para register().
• Os IDs de conector devem respeitar a RegEx /^[a-z0-9_-]+$/ (ou seja, permitem apenas letras minúsculas sem acento, números, sublinhados e hífens).

Métodos de registro (Registry methods)
Dentro do callback de wp_connectors_init, a instância de WP_Connector_Registry fornece os seguintes métodos:

• register( $id, $args ): Registra um novo conector. Retorna os dados do conector ou null caso haja falha.
• unregister( $id ): Remove um conector e retorna seus dados. Retorna null caso o conector não seja encontrado.
• is_registered( $id ): Checa se um conector existe.
• get_registered( $id ): Recupera os dados de um único conector.
• get_all_registered(): Recupera todos os conectores registrados.

Fora do escopo do callback wp_connectors_init, é recomendado usar as funções públicas da API (wp_get_connector(), wp_get_connectors(), wp_is_connector_registered()) ao invés de acessar a instância do registro diretamente.

O ciclo de vida de inicialização

Entender a sequência do processo de inicialização te ajudará a decidir o momento e o local certo para inserir seus hooks:

Durante a ação init, a função _wp_connectors_init() é processada e faz o seguinte:

1. Cria a instância única (singleton) do WP_Connector_Registry.
2. Registra os conectores nativos (Anthropic, Google, OpenAI) com valores padrões rígidos no código (hardcoded defaults).
3. Autodescobre os provedores provenientes do registro do WP AI Client e mescla seus metadados assumindo a precedência sobre os padrões.
4. Dispara a action wp_connectors_init — este é o local exato onde plugins devem realizar as sobrescritas de metadados ou os registros de novos conectores adicionais.

A action wp_connectors_init é o único ponto de entrada que tem o suporte oficial para alterar o registro. A tentativa de configuração da instância do registro fora da etapa de init irá acionar um aviso _doing_it_wrong().

Olhando para o futuro

A API de Conectores no WordPress 7.0 foi otimizada inicialmente para provedores de IA, mas a arquitetura de base foi projetada para escalar. No momento, apenas os conectores com autenticação via api_key recebem o tratamento visual completo no painel do administrador (admin UI).

No PHP, o registro já aceita livremente qualquer tipo de conector — a peça que falta, por enquanto, é apenas a integração do frontend com conectores baseados em diferentes mecanismos de autenticação.

As expectativas para futuros lançamentos incluem:

• Expandir o suporte aos métodos adicionais de autenticação, indo muito além de api_key e none.
• Oferecer ainda mais integrações de interface visual (UI) para outros tipos além de api_key.
• Fornecer uma API de registro em JavaScript, voltada ao cliente (client-side), para a criação de UIs de conectores personalizados.

Quando estas capacidades forem lançadas e estiverem ativas, a action wp_connectors_init funcionará como o hook principal para registrar os novos tipos de conectores.

Post original: https://make.wordpress.org/core/2026/03/18/introducing-the-connectors-api-in-wordpress-7-0/