Principais pontos do artigo
- Plugin próprio compensa quando a regra é do negócio, não existe pronta e precisa continuar funcionando depois de uma troca de tema.
- O único campo obrigatório do cabeçalho é Plugin Name; Requires at least, Requires PHP e Requires Plugins evitam problemas de compatibilidade e dependência.
- Ativação, desativação e desinstalação têm ganchos próprios, e apagar opções e tabelas do banco é trabalho da desinstalação.
- A validação acontece em homologação, com log de depuração ativo e teste de ativar, desativar e desinstalar.
O que é um plugin no WordPress
Plugin é um pacote de código PHP, às vezes com CSS, JavaScript e imagens, que acrescenta ou altera funções do WordPress sem mexer nos arquivos do núcleo. Cada plugin se conecta à plataforma por hooks: pontos predefinidos onde um código pode interagir com outro ou modificá-lo, segundo o manual de plugins[1]. Para o panorama da plataforma, o guia sobre o que é WordPress explica como núcleo, temas e plugins se combinam.
O tema cuida da apresentação e o plugin, da função. Uma regra de negócio escrita no functions.php some junto com o tema numa troca de layout, e esse costuma ser o motivo para levar código solto para um plugin. Plugins também estendem outros plugins: uma extensão do WooCommerce, plugin de loja mantido pela Automattic, é um plugin que usa os hooks dele, e o mesmo vale para quem registra blocos para o editor de blocos do projeto Gutenberg ou widgets para o Elementor.
Quando criar um plugin próprio
O esforço de um plugin próprio se justifica quando aparece pelo menos uma destas situações:
- a regra é específica do negócio, como cálculo de frete por região ou fluxo de aprovação de conteúdo;
- o site precisa se integrar a um sistema interno (ERP, CRM, API de parceiro) sem conector pronto;
- há tipos de conteúdo, campos ou permissões que precisam existir com qualquer tema;
- o
functions.phpacumulou regras de negócio que pouco têm a ver com a apresentação.
Se um plugin mantido, com atualizações frequentes, já cobre a necessidade, escrever do zero costuma sair mais caro ao longo do tempo, já que todo plugin próprio exige manutenção a cada versão nova do WordPress e do PHP. Para necessidades pequenas de layout, que cabem no tema, o caminho está no guia sobre como criar widget WordPress.
O que é preciso antes de começar
- Escopo escrito: o que o plugin faz, em quais telas e com quais dados.
- Prefixo único: o manual de boas práticas[2] pede pelo menos 4 a 5 caracteres em funções, classes e variáveis globais.
- Ambiente de homologação: cópia do site com o mesmo tema, plugins e versão de PHP.
- Editor de código e controle de versão: o código do plugin vive num repositório, e a publicação no site sai dele por deploy automatizado (uma GitHub Action, por exemplo), sem upload manual de arquivos.
- WP-CLI (opcional): agiliza a criação da estrutura, que já vem preparada para testes automatizados com PHPUnit.
Passo a passo para criar plugin no WordPress
1. Criar a estrutura (WP-CLI ou gerenciador de arquivos). O comando wp scaffold plugin sv-avisos gera o arquivo principal, readme.txt, phpunit.xml.dist, composer.json e as pastas tests e bin, segundo a documentação do WP-CLI[3]. Sem WP-CLI, basta criar a pasta sv-avisos em wp-content/plugins com o arquivo sv-avisos.php.
2. Escrever o cabeçalho (editor de código, topo do arquivo principal). Pelas regras de cabeçalho[4], só Plugin Name é obrigatório. Os campos usuais, com valores de exemplo, dentro do comentário PHP:
- Plugin Name: SV Avisos
- Description: menos de 140 caracteres
- Version: 1.0.0
- Requires at least e Requires PHP: versões mínimas testadas
- Requires Plugins: slugs do diretório WordPress.org separados por vírgula, como woocommerce; o campo tem efeito do WordPress 6.5 em diante, segundo o anúncio das dependências de plugin[5]
- License: GPLv2 or later
- Text Domain: sv-avisos
- Update URI: do WordPress 5.8 em diante, segundo o anúncio do campo[6]; em plugin privado, use a URL do seu servidor de atualização ou Update URI: false, e o WordPress não oferece a atualização de um plugin homônimo do diretório
3. Bloquear o acesso direto ao arquivo (logo abaixo do cabeçalho). Código: if ( ! defined( ‘ABSPATH’ ) ) { exit; }
4. Conectar ao WordPress com hooks (arquivo principal ou pasta includes). Uma action executa uma tarefa e não devolve nada; um filter recebe um valor, modifica e devolve. Código: add_filter( ‘the_content’, ‘svav_aviso’ ); function svav_aviso( $content ) { if ( is_singular( ‘post’ ) && in_the_loop() && is_main_query() ) { $content .= ‘
‘ . esc_html__( ‘Conteúdo revisado pela equipe editorial.’, ‘sv-avisos’ ) . ‘
‘; } return $content; }5. Tratar o ciclo de vida (arquivo principal e uninstall.php). Cada momento tem seu gancho, conforme a documentação de ativação e desativação[7] e de desinstalação[8]; a tabela abaixo resume.
6. Ativar em homologação (painel Plugins ou wp plugin activate sv-avisos). A validação começa aqui.
| Momento | Gancho | Uso típico |
|---|---|---|
| Ativação | register_activation_hook( __FILE__, ‘funcao’ ) | Criar opções padrão e, se houver tipo de conteúdo, chamar a mesma função de registro usada no hook init e em seguida flush_rewrite_rules(); o registro do tipo de conteúdo continua no init, a cada carregamento |
| Desativação | register_deactivation_hook( __FILE__, ‘funcao’ ) | Limpar cache e arquivos temporários, desfazer regras de reescrita |
| Desinstalação | uninstall.php ou register_uninstall_hook() | Apagar opções e tabelas próprias; uninstall.php confere a constante WP_UNINSTALL_PLUGIN antes |
Quanto tempo leva
O prazo acompanha o escopo. Um filtro simples como o do exemplo e um plugin com tela de configuração, integração externa e tabelas próprias são trabalhos de tamanhos muito diferentes, embora os dois passem por homologação e revisão de segurança.
Num plugin simples de resumo de posts por IA, feito pela Studio Visual para o portal institucional da Igreja Adventista em 2026, o plano dividiu o trabalho em quatro etapas: análise, desenvolvimento do plugin, homologação e QA. Homologação e QA ocuparam parte relevante do prazo, e quando há integração externa é frequente o plugin passar da estimativa inicial.
Como deixar o plugin seguro
1. Validar e sanitizar a entrada: sanitize_text_field(), sanitize_email() e similares antes de salvar.
2. Escapar a saída: esc_html(), esc_attr() e esc_url() conforme o contexto.
3. Usar nonce em formulários e ações: wp_nonce_field() na criação e check_admin_referer() ou wp_verify_nonce() na verificação.
4. Conferir permissão: a página de nonces[9] orienta proteger as funções com current_user_can(), porque nonce protege contra requisição forjada e a documentação desaconselha usá-lo para controle de acesso.
5. Consultar o banco com segurança: consultas preparadas com o método prepare() da classe wpdb, sem concatenar dado do usuário no SQL.
6. Proteger rotas REST e ações AJAX: rotas registradas com register_rest_route() precisam de permission_callback com current_user_can(), exigência do WordPress 5.5 em diante segundo as notas de mudança da REST API[10], e ações AJAX (wp_ajax_*) conferem nonce e permissão, como os formulários.
Erros mais comuns ao criar plugin
- Nomes sem prefixo: a função colide com outra de mesmo nome e o site para com erro fatal.
- Apagar dados na desativação: quem desativa para testar perde configurações; a limpeza fica na desinstalação.
- Carregar código de painel no site inteiro: o manual sugere carregar arquivos de administração só quando is_admin() é verdadeiro.
- Confiar só no nonce: sem current_user_can(), qualquer usuário logado pode disparar a ação.
- Não declarar Requires PHP e Requires at least: o plugin é ativado em ambiente incompatível e quebra.
- Testar direto em produção: o erro aparece para o visitante antes de aparecer para a equipe.
- ZIP com pasta de nome errado: um ZIP cuja pasta interna tem nome diferente do slug (por exemplo, sv-avisos-1.1.0/) cria uma segunda cópia do plugin, e a versão antiga continua ativa. O ZIP precisa conter a pasta sv-avisos/ com o arquivo principal dentro.
Como validar que deu certo
1. O plugin ativa sem aviso no painel e aparece como ativo em wp plugin list.
2. Com WP_DEBUG e WP_DEBUG_LOG ativos em homologação, o arquivo wp-content/debug.log fica sem avisos do plugin, conforme a página de depuração do WordPress[11], que desaconselha a depuração em site no ar.
3. A função entregue funciona no site, para o perfil de usuário certo e bloqueada para os demais.
4. Desativar mantém os dados; desinstalar remove opções e tabelas.
5. Depois de cada core update e de cada atualização de PHP, o teste se repete.
O que fazer quando dá errado
Se o site parar depois da ativação, o primeiro passo é desativar o plugin, pelo painel ou com wp plugin deactivate sv-avisos. Sem acesso ao painel, renomeie por FTP ou pelo gerenciador de arquivos só a pasta do plugin suspeito (sv-avisos para sv-avisos-off). Se o site continuar fora do ar, renomeie a pasta plugins inteira, como orientam as perguntas frequentes de solução de problemas do WordPress[12]. Com o site de volta, o debug.log da homologação mostra a linha do erro, e um conflito com outro plugin aparece ao reativar um por vez.
O que a experiência da Studio Visual mostra
A gente desenvolve plugins próprios para os sites WordPress que cria e mantém, e nas migrações é comum encontrar restos de plugins removidos ainda carregados no servidor ou no banco.
Em junho de 2026, a Studio Visual criou para a Revista Oeste, publicação digital de política que publica cerca de 200 matérias por dia, um plugin que gera o resumo de cada artigo por IA no momento da publicação, com edição liberada para o redator. No dia da estreia saíram 7 versões, por causa de aspas tipográficas em atributos HTML. Semanas depois, os resumos passaram a atribuir os fatos a meses errados. Ajustar o prompt não resolveu, porque o modelo não recebia a data de publicação. A correção foi enviar essa data junto com o texto, validada em cerca de 60 chamadas reais.
OPINIÃO DE ESPECIALISTA
“Plugin próprio não é a escolha certa quando um plugin mantido por terceiros resolve a regra ou quando ninguém vai cuidar do código depois da entrega. Tarefa de plugin sob medida com frequência passa da estimativa. No plugin de resumo por IA da Revista Oeste, o problema real apareceu depois da publicação: o modelo errava datas, e ajustar o prompt não resolveu. Plugin próprio é produto que pede manutenção, e se o orçamento só cobre a construção, prefiro configurar uma solução consolidada e documentar o limite.”
Vale fazer sozinho ou contratar
Um filtro pequeno, testado em homologação, está ao alcance de quem conhece PHP e a documentação do WordPress. Já um plugin com integração, dados de clientes ou pagamento pede revisão de segurança e alguém para manter o código nas próximas versões. Quando o plugin faz parte de um projeto maior, as etapas estão no guia sobre como criar site em WordPress.
Para plugins sob medida dentro de um projeto WordPress, a página de especialista em WordPress mostra como a Studio Visual trabalha com desenvolvimento na plataforma.
