Settings API: páginas de opções no WordPress

Atualizado em 19/06/2026

Quase todo plugin sério precisa de uma tela de configuração no admin. A tentação é montar um <form> à mão, processar o $_POST num hook qualquer e chamar update_option(). Funciona — e é por aí que entram XSS, CSRF e campos que "às vezes salvam". O WordPress já resolveu esse problema com a Settings API: um conjunto de funções que orquestra o ciclo inteiro (renderização, nonce, capability, sanitização e salvamento) de forma padronizada e auditável. Este guia mostra a arquitetura completa, com o porquê de cada peça.

Options API × Settings API: camadas distintas

Confundir as duas é o equívoco conceitual mais comum. São coisas diferentes, em níveis diferentes:

• Options API — a camada de persistência. get_option(), add_option() e update_option() leem e gravam valores na tabela wp_options. É de uso geral: você a chama em qualquer lugar (no front-end, em um cron, no admin) para ler ou salvar uma configuração.
• Settings API — a camada de interface e fluxo. Não armazena nada por si só; ela registra quais opções existem, desenha as seções e campos no admin e intercepta o envio do formulário para o arquivo options.php, validando o nonce e a capability antes de chamar a Options API por baixo.

Dito de outro modo: a Settings API orquestra o formulário; a Options API guarda o dado. Você pode usar a Options API sem a Settings API (para um simples update_option() num hook próprio), mas dificilmente o contrário compensa — a Settings API só faz sentido junto da Options API.

O mapa das funções

Antes do código, fixe o papel de cada função. Há dois grupos: o que você registra (no admin_init) e o que você imprime (no HTML da página).

1. A página no menu (hook admin_menu)

Primeiro registramos a página de admin. Para configurações, o lugar canônico é o submenu Configurações, via add_options_page(); para algo de primeiro nível, add_menu_page(). Em ambos, o quarto argumento é a capability exigida — use manage_options para restringir a administradores. O registro acontece no hook admin_menu:

<?php
add_action( 'admin_menu', 'dwp_registrar_pagina_opcoes' );

function dwp_registrar_pagina_opcoes() {
    add_options_page(
        'Configurações do Meu Plugin',  // <title> da página
        'Meu Plugin',                    // rótulo no menu Configurações
        'manage_options',                // capability exigida
        'meu-plugin',                    // slug (vira ?page=meu-plugin)
        'dwp_render_pagina_opcoes'       // callback que imprime o HTML
    );
}

O slug (meu-plugin) identifica a página na URL e — atenção — é o mesmo identificador que usaremos em do_settings_sections() e como contexto em add_settings_section()/add_settings_field(). A capability não é decoração: ela é a autorização. Mesmo que alguém descubra a URL, o WordPress nega o acesso a quem não tem manage_options.

2. O HTML da página (o callback de render)

O callback informado acima imprime a tela. A estrutura é sempre a mesma e cada linha tem função: o <form> aponta para options.php via POST; settings_fields() injeta o nonce e o grupo; do_settings_sections() desenha os campos; submit_button() imprime o botão "Salvar alterações".

<?php
function dwp_render_pagina_opcoes() {
    // Defesa em profundidade: nega quem não tem a capability.
    if ( ! current_user_can( 'manage_options' ) ) {
        return;
    }
    ?>
    <div class="wrap">
        <h1><?php echo esc_html( get_admin_page_title() ); ?></h1>

        <?php settings_errors(); // exibe mensagens add_settings_error() ?>

        <form action="options.php" method="post">
            <?php
            // Imprime nonce + option_page do grupo (CSRF + roteamento).
            settings_fields( 'meu_plugin_grupo' );

            // Renderiza seções e campos registrados para esta página.
            do_settings_sections( 'meu-plugin' );

            // Botão "Salvar alterações".
            submit_button();
            ?>
        </form>
    </div>
    <?php
}

Repare que o formulário não tem action de salvamento próprio: ele posta para options.php, que é o handler do núcleo. É ele quem lê o option_page oculto (impresso por settings_fields()), valida o nonce, confere a capability, chama o sanitize_callback e grava. Por isso o grupo (meu_plugin_grupo) tem que ser idêntico ao do register_setting() — é a chave que liga o envio ao registro.

3. O registro (hook admin_init)

Agora a peça central. Tudo que a Settings API precisa conhecer — a opção, suas seções e campos — é registrado no hook admin_init. Adotamos a boa prática de guardar tudo num único array de opção (meu_plugin_opcoes):

<?php
add_action( 'admin_init', 'dwp_registrar_settings' );

function dwp_registrar_settings() {

    // (a) Declara a opção, o grupo e quem sanitiza antes de salvar.
    register_setting(
        'meu_plugin_grupo',                 // grupo (= settings_fields)
        'meu_plugin_opcoes',                // nome da opção (array único)
        array(
            'type'              => 'array',
            'sanitize_callback' => 'dwp_sanitizar_opcoes',
            'default'           => array(),
        )
    );

    // (b) Uma seção visual dentro da página 'meu-plugin'.
    add_settings_section(
        'meu_plugin_secao_geral',           // id da seção
        'Configurações gerais',             // título exibido
        'dwp_descricao_secao',              // callback de descrição (pode ser null)
        'meu-plugin'                        // página (= do_settings_sections / slug)
    );

    // (c) Os campos, ligados à seção acima.
    add_settings_field(
        'campo_email',                      // id do campo
        'E-mail de notificação',            // <label>
        'dwp_render_campo_email',           // callback que imprime o input
        'meu-plugin',                       // página
        'meu_plugin_secao_geral',           // seção a que pertence
        array( 'label_for' => 'campo_email' ) // associa o <label> ao input
    );

    add_settings_field(
        'campo_limite',
        'Limite de itens',
        'dwp_render_campo_limite',
        'meu-plugin',
        'meu_plugin_secao_geral',
        array( 'label_for' => 'campo_limite' )
    );
}

function dwp_descricao_secao() {
    echo '<p>Ajustes gerais do plugin.</p>';
}

Três identificadores precisam ser consistentes ou nada funciona: o grupo (meu_plugin_grupo, igual em register_setting e settings_fields), a página (meu-plugin, igual em add_settings_section, add_settings_field e do_settings_sections) e o nome da opção (meu_plugin_opcoes). O label_for não é obrigatório, mas melhora a acessibilidade ao ligar o <label> da coluna esquerda ao id do campo.

4. O callback de um campo (ler e escapar)

Cada campo registrado precisa de um callback que imprime o <input>. Aqui valem duas regras: leia o valor atual com get_option() (lembrando que guardamos um array) e escape a saída com esc_attr(). Como o name usa a notação de array, o WordPress entrega o valor já agrupado em $_POST['meu_plugin_opcoes']:

<?php
function dwp_render_campo_email() {
    $opcoes = get_option( 'meu_plugin_opcoes', array() );
    $valor  = isset( $opcoes['email'] ) ? $opcoes['email'] : '';
    ?>
    <input type="email"
           id="campo_email"
           name="meu_plugin_opcoes[email]"
           value="<?php echo esc_attr( $valor ); ?>"
           class="regular-text">
    <p class="description">Receberá os avisos do plugin.</p>
    <?php
}

function dwp_render_campo_limite() {
    $opcoes = get_option( 'meu_plugin_opcoes', array() );
    $valor  = isset( $opcoes['limite'] ) ? (int) $opcoes['limite'] : 10;
    ?>
    <input type="number" min="1" max="100" step="1"
           id="campo_limite"
           name="meu_plugin_opcoes[limite]"
           value="<?php echo esc_attr( $valor ); ?>">
    <?php
}

O name="meu_plugin_opcoes[email]" é o que faz tudo cair sob a mesma opção: o navegador envia meu_plugin_opcoes como um array com as chaves email e limite. Por isso o sanitize_callback receberá o array inteiro. E note: mesmo num campo numérico, escapamos com esc_attr() na saída — escapar é função do contexto de impressão, não da confiança no dado.

5. O sanitize_callback (validar é aqui)

Este é o coração da segurança da tela. O sanitize_callback recebe o valor cru do $_POST e retorna o que será gravado. Como usamos um array, ele recebe o array inteiro e devolvemos uma versão limpa — campo a campo, descartando qualquer chave que não esperamos:

<?php
function dwp_sanitizar_opcoes( $entrada ) {
    $saida = array();

    // E-mail: valida e normaliza; se inválido, avisa e mantém o anterior.
    $email = isset( $entrada['email'] ) ? sanitize_email( $entrada['email'] ) : '';
    if ( '' !== $email && ! is_email( $email ) ) {
        add_settings_error(
            'meu_plugin_opcoes',
            'email_invalido',
            'O e-mail informado é inválido. O valor anterior foi mantido.',
            'error'
        );
        $antigas        = get_option( 'meu_plugin_opcoes', array() );
        $saida['email'] = isset( $antigas['email'] ) ? $antigas['email'] : '';
    } else {
        $saida['email'] = $email;
    }

    // Limite: inteiro forçado para a faixa 1..100.
    $limite           = isset( $entrada['limite'] ) ? (int) $entrada['limite'] : 10;
    $saida['limite']  = max( 1, min( 100, $limite ) );

    return $saida; // SÓ o que está aqui é salvo.
}

Feedback ao usuário com add_settings_error()

No menu Configurações, o WordPress já mostra automaticamente o aviso "Configurações salvas." quando o salvamento ocorre. Para mensagens próprias — sobretudo erros de validação — use add_settings_error() dentro do sanitize_callback (como no exemplo acima) e garanta a chamada de settings_errors() no topo da página. Em páginas fora do menu Configurações, o settings_errors() é obrigatório até para o aviso de sucesso aparecer.

Armadilhas comuns

Boas práticas

• Uma opção em array, não dezenas soltas. Menos linhas em wp_options, um register_setting, um sanitize_callback e limpeza trivial na desinstalação (delete_option( 'meu_plugin_opcoes' )).
• Sanitize na entrada, escape na saída. São deveres independentes: o sanitize_callback limpa o que entra; esc_attr()/esc_textarea() protegem o que sai. Veja segurança no código.
• Prefixe tudo (grupo, opção, funções) com o slug do seu plugin para evitar colisões no escopo global.
• Registre nos hooks certos. Menu em admin_menu, configurações em admin_init — essa separação está documentada e é o que faz o options.php reconhecer suas opções. Entenda os hooks envolvidos.
• Use os helpers do form do admin — checked(), selected() e disabled() — para marcar estados sem if espalhados pelo HTML.
• Defina show_in_rest em register_setting() quando a opção também precisar ser lida/escrita via REST API (por exemplo, por um bloco do editor).

Com esse esqueleto você tem uma tela de opções segura por construção: o núcleo cuida do nonce, da capability e do salvamento, e você concentra a inteligência onde ela importa — no sanitize_callback. A partir daí, adicionar campos é repetir o trio add_settings_field → callback de render → chave no sanitizador.