Como criar uma tela de configuração para o seu plugin WordPress com a Settings API — Parte 1

Criou o seu plugin e agora quer criar uma tela de configuração para ele? Então esse post e esse vídeo são para você!

Parte 1: Como criar e validar seus campos com a API de configurações do WordPress
Parte 2: Como criar seções e páginas no Painel do WP

Vamos usar a API de Configurações (Settings API) do WordPress.

Os passos essenciais para conseguir o que queremos são:

Criar cada configuração (setting) com a função register_setting()
Criar um campo para cada configuração com a função add_settings_field()

Opcionalmente, você também pode:

Criar uma ou mais seções para os seus campos com a função add_settings_section()
Criar uma página para exibir os seus campos com a função add_menu_page() ou similar

Vamos ver estes dois passos na Parte 2.

O mais básico: campo em página de configuração já existente

Para chamar as funções necessárias, precisamos usar a action admin_init do WP. Se você também quer expor as configurações na API REST do WordPress, no endpoint wp-json/wp/v2/settings, será preciso também usar a action rest_api_init. Fique tranquilo, este endpoint só é visível para usuários autorizados.

A função register_setting() aceita três argumentos:

$option_group (obrigatório): O nome do grupo, ou melhor, da página de configuração que estamos criando. Os grupos/páginas nativos do WP são ‘general’, ‘discussion’, ‘media’, ‘reading’, ‘writing’, ‘misc’, ‘options’ e ‘privacy’, mas na parte 2 vamos ver como podemos criar uma página nova.
$option_name (obrigatório): O slug da nossa configuração. Essa é a string que vamos usar na chamada para get_option().
$args (opcional): Os argumentos para a criação da configuração. Aqui você pode, por exemplo, passar uma função de higienização usando o índice sanitize_callback. É possível ver a lista completa de valores possíveis na documentação.

Para que o usuário possa realmente interagir com a configuração, também é preciso criar um campo. Para isso vamos usar a função add_settings_field(). Esta função aceita 6 parâmetros:

$id (obrigatório): O ID do campo. Não necessariamente o mesmo ID da setting, que definimos anteriormente.
$title (obrigatório): Isso mesmo, o título do campo.
$callback (obrigatório): A função responsável por gerar o HTML do campo. É nesta função que vamos criar o input[text], o select ou o checkbox do nosso campo.
$page (obrigatório): O slug da página de configuração onde o campo deve ser exibido. Deve ter o mesmo valor que o primeiro parâmetro da register_setting(). Caso contrário o campo será exibido, mas o valor não será salvo.
$section (opcional): O slug da seção da página que definimos no parâmetro anterior.
$args (opcional): Array com argumentos extras. label_for e class são as chaves aceitadas por padrão, mas você pode adicionar qualquer coisa.

function minhas_configuracoes() {
	register_setting(
		'general',
		'chave_api_minha_integracao',
		array(
			'sanitize_callback' => function( $value ) {
				if ( ! preg_match( '/API-[0-9]{4}-[A-Z]{3}/', $value ) ) {
					add_settings_error(
						'chave_api_minha_integracao',
						esc_attr( 'chave_api_minha_integracao_erro' ),
						'Chave API no formato errado.',
						'error'
					);
					return get_option( 'chave_api_minha_integracao' );
				}
				return $value;
			},
		)
	);

	add_settings_field(
		'chave_api_minha_integracao',
		'Chave API da minha integração',
		function( $args ) {
			$options = get_option( 'chave_api_minha_integracao' );
			?>
			<input
				type="text"
				id="<?php echo esc_attr( $args['label_for'] ); ?>"
				name="chave_api_minha_integracao"
				value="<?php echo esc_attr( $options ); ?>">
			<?php
		},
		'general',
		'default',
		[
			'label_for' => 'chave_api_minha_integracao_html_id',
			'class'     => 'classe-html-tr',
		]
	);
}
add_action( 'admin_init', 'minhas_configuracoes' );

Na parte 2 criamos uma página nova, ao invés de adicionar o nosso campo em uma página já existente. Corre lá!

Ir para a parte 2: Como criar seções e páginas no Painel do WP ►