Options API

Options API WordPress é o conjunto de funções nativas do CMS para armazenar e recuperar configurações persistentes no banco de dados, na tabela wp_options. As três funções centrais são add_option(), get_option() e update_option(), todas operando sobre pares de chave-valor. Quase todo plugin e tema usa Options API por baixo: configurações do painel, integrações com APIs, flags de feature, dados estruturados em arrays serializados. É a forma padrão de salvar estado de aplicação dentro do WordPress.

O que é a Options API

A Options API é a camada de abstração do WordPress sobre a tabela wp_options do banco. Em vez de você executar queries SQL para salvar e ler configuração, chama as funções da API e o WordPress gerencia o resto: serialização de tipos complexos, cache em memória, hooks para outros plugins observarem mudanças, fallback para valor default.

A tabela wp_options tem estrutura simples: option_id, option_name, option_value, autoload. Cada linha é uma chave-valor. option_name é único e funciona como chave primária lógica. option_value pode armazenar string, número ou estrutura complexa serializada (array, objeto). autoload define se a opção carrega automaticamente em toda requisição.

A API existe desde os primeiros dias do WordPress e é uma das peças mais estáveis do core. Funções get_option e update_option não mudaram em quase duas décadas, o que torna o aprendizado válido por anos sem precisar atualizar.

Para quem desenvolve plugin, Options API é o caminho de menor resistência para configurações: integração com Settings API entrega tela admin pronta, cache vem grátis, hooks de save/update permitem reagir a mudanças. Combinada com a tabela wp_options bem mantida, garante que dados não vazem entre plugins ou conflitem entre si.

Como funciona a Options API

get_option(‘chave’, ‘default’) é a função de leitura. Recebe nome da opção e valor padrão (opcional). Retorna o valor armazenado, ou o default se a chave não existir, ou false se não existir e nenhum default for passado. WordPress mantém cache em memória durante a requisição: chamar get_option duas vezes não consulta o banco duas vezes.

update_option(‘chave’, ‘valor’) é a função de escrita. Atualiza o valor se a chave existir, ou cria se não existir. Retorna true se houve mudança, false se o valor era idêntico ao já armazenado. Internamente roda update_option ou add_option dependendo do estado.

add_option(‘chave’, ‘valor’, ”, ‘no’) força criação. Útil quando você quer evitar update acidental de chave existente. O parâmetro autoload (yes/no) é crítico para performance: opções com autoload=yes carregam automaticamente em toda requisição, somando peso ao boot. autoload=no faz a opção carregar só quando explicitamente requisitada.

delete_option(‘chave’) remove. Desinstaladores de plugin (uninstall.php) costumam chamar delete_option em loop para todas as suas opções, deixando o banco limpo. Sem isso, banco acumula lixo de plugins descartados.

Hooks pre_option_nome_da_opcao, option_nome_da_opcao, update_option_nome_da_opcao e add_option_nome_da_opcao permitem interceptar e modificar fluxos. Plugins podem injetar valor calculado, validar input, disparar webhooks em mudança. Toda essa flexibilidade vem grátis pela API.

Boas práticas de uso

Prefixe sempre o nome da opção. Em vez de “api_key”, use “meuplugin_api_key”. WordPress não tem namespace nativo, então prefixo é o jeito de evitar colisão entre plugins. Plugins sem prefixo causam bug nojento: dois plugins escrevem na mesma chave e um sobrescreve o outro.

Use autoload=no para opções não usadas em todo request. Configurações de página de admin, dados de import, flags de operação one-shot: nada disso precisa carregar em frontend. Sites com 200 opções autoload=yes em wp_options sofrem de boot lento. Plugins desenvolvidos com displicência são causa comum.

Para arrays de configuração relacionada, agrupe num único array em vez de criar chave por campo. Em vez de meuplugin_email, meuplugin_servidor, meuplugin_porta, salve um único get_option(‘meuplugin_settings’) com array contendo email, servidor, porta. Reduz queries, simplifica código, facilita backup/restore.

Não armazene dados que mudam frequente em Options API. Cada update_option é INSERT/UPDATE no banco e invalidação de cache. Contadores de visita, hits por usuário, dados temporários: use Transients ou tabelas customizadas. Options API é para configuração, não para dados operacionais voláteis.

Para dados sensíveis (chaves de API, tokens), considere ainda mais cuidado. Banco WordPress acaba em backup, e backup vaza. Plugins podem criptografar antes de salvar, ou usar wp-config.php para credenciais críticas. WP-CLI permite gerenciar opções via comando wp option, útil em scripts de deploy.

Options API vs Transients vs Settings

Transient API é a primazinha que usa wp_options por baixo mas com TTL. set_transient(‘chave’, ‘valor’, HOUR_IN_SECONDS) salva por uma hora; depois disso o valor é descartado. Para cache de queries pesadas, resultados de API externa, dados que podem expirar, transients são ideais. Combine com Transient API bem usada e queries em banco de dados WordPress ficam mais leves.

Settings API é a camada acima da Options API que gera telas de configuração no admin. register_setting, add_settings_section, add_settings_field criam página de admin com forma e validação. Por baixo, salva tudo via update_option. Dois mundos: Options API guarda dados, Settings API renderiza interface para o usuário editar.

Para decidir qual usar, regra prática: dado precisa de TTL? Transients. Dado é configuração persistente do site? Options API. Quer expor ao usuário no painel para editar? Settings API por cima da Options API. Dado é volume grande, com queries específicas? Tabela customizada com dbDelta.

Performance é o argumento decisivo. Site com 10 plugins mal configurados cada um com 50 opções autoload=yes tem 500 linhas carregando em todo request. Boot do WordPress passa de 200ms para 800ms. Audit de wp_options removendo autoload desnecessário é uma das otimizações mais subestimadas.

Para sites WordPress que precisam manter wp_options enxuta sem auditoria manual recorrente, a FULL Services entrega o WP Optimize já licenciado dentro da plataforma, com limpeza programada de transients expirados, identificação de opções autoload pesadas e relatório de tamanho da tabela direto no painel. É a forma de manter a Options API saudável conforme o site cresce, sem o time precisar mexer em SQL toda semana.