1. Visão geral do boot
Quando o servidor recebe uma requisição, o WordPress segue uma cadeia de arquivos que constroem o ambiente, conectam ao banco, registram hooks, carregam plugins e invocam o tema ativo. Compreender essa trilha permite diagnosticar problemas de forma rápida e segura.
Meta técnica reconhecer onde colocar logs, como ativar debug, em que ponto os plugins entram, o que o tema pode fazer e como o core decide o template final.
2. Mapa do carregamento do core
Fluxo de inicialização
index.php
└── wp-blog-header.php
└── wp-load.php
└── wp-config.php # Credenciais de DB, chaves, constantes
└── wp-settings.php
├── Carrega wp-includes/*
├── Registra e aciona hooks iniciais
├── Carrega plugins ativos
└── Invoca template-loader → tema ativo
index.php
Ponto de entrada. Encaminha para o bootstrap padrão do WordPress.
wp-blog-header.php
Prepara a consulta principal e a pilha do front.
wp-load.php
Localiza e inclui o arquivo de configuração do site.
wp-config.php
Define conexão com banco, chaves, e constantes de execução.
wp-settings.php
Inicializa o core, carrega bibliotecas, plugins e chama o template loader.
3. Constantes e modos de execução
Estas constantes controlam comportamento em desenvolvimento e produção. Ative apenas em ambiente local.
wp-config.php — bloco de debug seguro
// Debug de código
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
// Debug de scripts e estilos
define('SCRIPT_DEBUG', true);
// Cache de objetos
// define('WP_CACHE', true); // Ativar somente quando houver cache configurado
// Banco e site
define('DB_NAME', 'wp_estudos');
define('DB_USER', 'wp_user');
define('DB_PASSWORD', 'senha_forte');
define('DB_HOST', 'localhost');Princípio logar no arquivo e não na tela. Isso protege a experiência do usuário e mantém rastreabilidade.
4. Hooks iniciais e ordem de execução
Os hooks permitem inserir código em pontos previsíveis. A ordem a seguir é simplificada e suficiente para desenvolvimento do front.
| Hook | Quando ocorre | Uso típico |
|---|---|---|
| muplugins_loaded | Após must use plugins | Inicializações críticas da infraestrutura |
| plugins_loaded | Após plugins comuns | Registrar serviços, internacionalização |
| after_setup_theme | Antes dos templates | Adicionar suporte a features do tema |
| init | Inicialização geral | Registrar post types e taxonomias |
| wp_loaded | Logo antes da saída | Ajustes finais globais |
| wp_enqueue_scripts | Antes do render | Enfileirar CSS e JS do front |
functions.php — exemplos mínimos
add_action('after_setup_theme', function(){
add_theme_support('post-thumbnails');
add_theme_support('title-tag');
});
add_action('init', function(){
register_post_type('portfolio', [
'label' => 'Portfolio',
'public' => true,
'supports' => ['title','editor','thumbnail']
]);
});
add_action('wp_enqueue_scripts', function(){
wp_enqueue_style('site', get_stylesheet_uri(), [], '1.0');
wp_enqueue_script('site-js', get_template_directory_uri().'/assets/site.js', [], '1.0', true);
});5. Template loader e decisão de template
O carregador de template aplica regras de seleção para encontrar o arquivo correto do tema. Segue uma visão resumida do processo.
Árvore de decisão
Requisição →
└─ Consulta principal resolve contexto
├─ is_singular('post') → single-post.php → single.php → singular.php → index.php
├─ is_page() → page-{slug|id}.php → page.php → singular.php → index.php
├─ is_category() → category.php → archive.php → index.php
├─ is_tag() ou taxonomy() → tag.php | taxonomy.php → archive.php → index.php
├─ is_search() → search.php → index.php
└─ 404 → 404.php → index.php
Teste rápido de template em uso
// Em functions.php apenas durante desenvolvimento
add_action('template_include', function($template){
error_log('Template usando: ' . $template);
return $template;
});6. Debug seguro e diagnóstico
É importante logar de forma privada, inspecionar consultas e isolar problemas sem afetar usuários.
Inspeção de query principal
// Em development apenas
add_action('wp', function($wp){
// Contextos
if (is_home()) error_log('Contexto: home');
if (is_singular()) error_log('Contexto: singular');
if (is_archive()) error_log('Contexto: archive');
// Query vars
error_log(print_r($wp->query_vars, true));
});
Relatório de hooks disparados
// Em development apenas
add_action('all', function($hook){
static $count = 0;
if ($count < 30) { // Evitar logs gigantes
error_log('Hook: ' . $hook);
$count++;
}
});Sugestão use um plugin de log de consultas quando necessário. Em produção desative tudo que possa expor dados sensíveis.
7. Erros comuns e como evitar
- Editar arquivos do core. Sempre usar tema filho e plugins para extensões.
- Exibir erros no navegador em produção. Prefira log em arquivo.
- Carregar scripts direto no header sem usar wp_enqueue_scripts. Use a fila oficial.
- Alterar query global com query_posts. Usar WP_Query e resetar o contexto ao final.
- Deixar autoload inchado na tabela wp_options. Definir autoload somente para dados realmente necessários.
Impacto práticas inseguras e alterações diretas no core dificultam atualização e suporte e geram riscos para o projeto.
8. Exercícios práticos
- Ative debug seguro no wp-config e confirme que o log é gerado em wp-content.
- Adicione um post type simples no hook init e valide a presença no painel.
- Implemente o log do template_include e navegue por páginas para observar a hierarquia em ação.
- Crie uma página e associe um page slug específico. Crie um arquivo page-slug.php no tema e valide a seleção correta.
- Enfileire um arquivo JS no hook wp_enqueue_scripts e confirme a presença no front através da ferramenta de rede do navegador.
Modelo de functions.php para os exercícios
<?php
// 1. Debug seguro já configurado no wp-config
// 2. CPT simples
add_action('init', function(){
register_post_type('lab', [
'label' => 'Laboratório',
'public' => true,
'supports' => ['title','editor','thumbnail']
]);
});
// 3. Log de template em uso
add_action('template_include', function($template){
error_log('Template usando: ' . $template);
return $template;
});
// 4. Enfileirar JS do tema
add_action('wp_enqueue_scripts', function(){
wp_enqueue_style('site', get_stylesheet_uri(), [], '1.0');
wp_enqueue_script('lab-js', get_template_directory_uri() . '/assets/lab.js', [], '1.0', true);
});