🛠 2 Formas de obter o caminho raiz do WordPress

Inclui um ficheiro no functions.php e o WordPress não o encontra. Parece-lhe familiar? A razão é quase sempre um caminho incorreto para a pasta raiz.

Um caminho manualmente fixo como /var/www/html/ quebra quando muda para um servidor diferente. E um ../../wp-content/plugins/ rigidamente embutido deixa de funcionar quando a estrutura de diretórios se altera. Felizmente, o WordPress fornece duas formas padrão de obter o caminho absoluto para a raiz do site, sem adivinhações. Ambas incluem uma barra final por defeito, pelo que concatenar subcaminhos não exige uma / extra.

No final deste artigo, saberá exatamente quando usar get_home_path() e quando usar ABSPATH, e porque é que coincidem em alguns projetos, mas devolvem diretórios diferentes noutros. Como bónus, abordaremos um erro comum de barra dupla e um cenário para scripts cron externos.

💡 Visão geral rápida:

• Abra o functions.php do seu tema e inclua wp-admin/includes/file.php, depois chame get_home_path() para obter o caminho absoluto com uma barra final
• Use a constante ABSPATH do wp-config.php; está disponível globalmente, não requer inclusão manual e funciona até no front-end
• Com uma estrutura de diretórios não padrão (Bedrock, núcleo realocado), compare a saída de ambos os métodos num servidor de teste; podem apontar para pastas diferentes
• Para plugins e temas distribuídos através do diretório do WordPress.org, use ABSPATH; é o padrão que funciona de forma fiável em qualquer alojamento

1. Get_home_path(): o caminho através da API de administração

A função get_home_path() está documentada na documentação oficial do WordPress e devolve o caminho absoluto do sistema de ficheiros para a raiz da instalação, o diretório que contém wp-admin, wp-includes e wp-content. Ao contrário da codificação manual, não depende do ambiente de alojamento e não quebra quando migra.

A principal vantagem: não precisa de adivinhar se o site está implantado na raiz do domínio ou num subdiretório. A função descobre e devolve, por exemplo, /var/www/html/ para uma instalação padrão ou /home/user/site.com/wordpress/ para um site numa subpasta. Nada de ../../ nem edições manuais de configuração.

O ficheiro que contém a função está localizado em wp-admin/includes/file.php, pelo que get_home_path() não está disponível diretamente num tema ou no front-end. Para a usar fora da área de administração, inclua o ficheiro manualmente primeiro. Adicione o código ao functions.php do seu tema filho ou através de um plugin como o Code Snippets:

1
// Include the file with the function — without it get_home_path() will cause a fatal error
2
require_once ABSPATH . 'wp-admin/includes/file.php';
3
 
4
// Get the absolute path to the WordPress root
5
$root = get_home_path();
6
 
7
// Example: include the update.php file from wp-admin
8
require_once $root . 'wp-admin/update.php';

Aqui, require_once com um caminho construído a partir de ABSPATH carrega o ficheiro de administração apenas uma vez; uma segunda inclusão não causará conflito. Depois disso, get_home_path() fica disponível em qualquer parte do tema.

Nota: a barra final já está incluída na string devolvida. Concatene subcaminhos sem uma / extra no início: $root . 'wp-admin/update.php', e não $root . '/wp-admin/update.php'. O PHP engolirá silenciosamente uma barra dupla na maioria dos sistemas de ficheiros, mas algumas verificações rigorosas de file_exists() podem tropeçar.

2. ABSPATH: a constante diretamente do wp-config.php

ABSPATH é uma constante que o WordPress define no wp-config.php durante o arranque. Num ficheiro padrão, tem este aspeto:

1
if (!defined('ABSPATH')) {
2
    define('ABSPATH', __DIR__ . '/');
3
}

__DIR__ devolve o diretório onde o próprio wp-config.php reside, e essa é a raiz do WordPress. A constante está disponível globalmente: em temas, plugins, no front-end, no admin, no WP-CLI. Não é necessário require_once para a carregar; já está em memória a partir do momento em que o núcleo arranca.

A utilização é trivial: use ABSPATH em qualquer lugar onde seja necessário um caminho absoluto:

1
// Save the path to a variable for readability
2
$rootPath = ABSPATH;
3
 
4
// Include the file from wp-admin
5
require_once ABSPATH . 'wp-admin/update.php';
6
 
7
// Or load a custom file from the root
8
include_once ABSPATH . 'custom-cron.php';

A barra final também está presente aqui, comportamento idêntico ao get_home_path(). O padrão require_once ABSPATH . 'wp-admin/update.php' funcionará em qualquer alojamento, em qualquer estrutura de diretórios, sem ajustes de caminho. É exatamente por isso que a maioria dos plugins no diretório do WordPress.org usa ABSPATH em vez de get_home_path(): a constante não requer inclusão manual de ficheiros e não depende do contexto da chamada.

Quando get_home_path() e ABSPATH devolvem diretórios diferentes

Numa instalação padrão do WordPress, ambas as construções devolvem a mesma string. Mas há dois cenários onde divergem, e se não os conhecer, um bug pode viver no seu código durante meses.

O núcleo é realocado da raiz do documento. Alguns fornecedores de alojamento (Kinsta, WP Engine) e configurações personalizadas colocam os ficheiros do núcleo num diretório separado, com o wp-config.php um nível acima. Neste caso, ABSPATH aponta para a pasta que contém o wp-config.php, enquanto get_home_path() aponta para o subdiretório com o núcleo. No WordPress StackExchange, os programadores partilham um exemplo real: ABSPATH = /www/site/, enquanto get_home_path() = /www/site/wp/. Uma diferença de um diretório, e o require_once falha com um erro fatal.

Bedrock e outras estruturas não padrão. No Bedrock da Roots, a raiz do site (web/wp/) é separada da raiz do projeto, que contém config/, vendor/ e web/. O ABSPATH no Bedrock aponta para web/wp/, enquanto o get_home_path() se orienta com base nas configurações de multisite e no URL inicial. Na prática, o get_home_path() no Bedrock pode devolver um caminho para web/wp/ que coincide com o ABSPATH, mas não confie nisso; verifique no seu projeto específico.

Conclusão prática: se está a escrever um plugin para o diretório do WordPress.org, use ABSPATH; está disponível em todo o lado sem inclusões extra. Se está a escrever código para um site específico com uma estrutura não padrão, verifique ambas as constantes num ambiente de teste e escolha a que aponta para onde realmente precisa. Cinco minutos de comparação num servidor de teste pouparão horas de depuração em produção.

Há mais uma nuance com temas: se o seu tema for distribuído no ThemeForest ou no diretório do WordPress.org, use sempre ABSPATH; é garantido que está definido em qualquer alojamento do cliente. O get_home_path() pode não funcionar se o tema o chamar antes de a área de administração carregar.

O pequeno vídeo acima demonstra visualmente como o ABSPATH protege os plugins da execução direta e porque é que o padrão defined('ABSPATH') or die é um padrão de segurança para qualquer ficheiro PHP no ecossistema WordPress.

⁉️🤔 Perguntas frequentes

Qual é mais rápido: get_home_path() ou ABSPATH?

ABSPATH é uma constante: o seu valor é definido uma vez quando o WordPress carrega e fica armazenado em memória. get_home_path() é uma função que, na primeira chamada, analisa o URL inicial e calcula o caminho relativo ao sistema de ficheiros. A diferença de velocidade é ínfima (microssegundos por chamada), mas se o caminho for solicitado dezenas de vezes num único pedido HTTP, armazene ABSPATH numa variável no topo do seu script e use essa.

Preciso de incluir manualmente o ABSPATH nos meus próprios ficheiros?

Se o seu código corre no contexto do WordPress (tema, plugin, handler AJAX), o ABSPATH já está definido; não precisa de incluir nada. A verificação if (!defined('ABSPATH')) { exit; } no topo de um ficheiro PHP autónomo na raiz do site é uma boa prática de segurança: bloqueia a execução direta do script contornando o WordPress e protege contra fugas de dados através de um pedido HTTP direto ao ficheiro.

Posso usar o ABSPATH num script cron externo?

Pode, mas com cautela. Se o script residir fora da instalação do WordPress, carregue o wp-load.php: require_once '/path/to/wp-load.php';. Depois disso, o ABSPATH fica disponível. Tenha em mente: chamar o wp-load.php diretamente carrega todo o núcleo e todos os plugins ativos, o que é excessivo para tarefas cron frequentes. Para projetos de alto tráfego, é melhor mover a lógica para um comando WP-CLI.

O get_home_path() devolve um caminho com barra dupla?

Não. A função tem a garantia de devolver uma única barra final. Uma barra dupla só pode aparecer se adicionar uma / no início do subcaminho você mesmo: get_home_path() . '/wp-admin/'. A forma correta é sem barra inicial: get_home_path() . 'wp-admin/'. Na maioria dos sistemas Linux, uma barra dupla é equivalente a uma única, mas não confie nisso; verificações de file_exists() em algumas configurações podem devolver false.

Como é que o caminho raiz difere do URL inicial?

O caminho raiz (/var/www/html/) é o sistema de ficheiros do servidor. O URL inicial (https://site.com) é o endereço que o navegador vê. Para obter um URL, use home_url(); para um caminho do sistema de ficheiros, use get_home_path() ou ABSPATH. Não os misture: require_once espera um caminho do sistema de ficheiros, wp_remote_get() espera um URL. Se os confundir, obterá ou false do file_exists() ou um pedido HTTP quebrado para um caminho local.

O que usar no seu projeto: a conclusão final

Para a grande maioria das tarefas, o ABSPATH é suficiente. A constante está disponível imediatamente após o WordPress carregar, não requer inclusão manual de ficheiros e funciona de forma idêntica em qualquer alojamento. Se está a escrever um plugin ou tema para distribuição, apenas ABSPATH, sem alternativas.

Se administra um site com uma estrutura de diretórios não padrão (núcleo realocado, Bedrock, multisite com URLs iniciais diferentes), gaste cinco minutos e compare a saída de get_home_path() e ABSPATH num ambiente de teste. Uma discrepância de um diretório pode custar horas de depuração em produção.

Qual é o método que usa, get_home_path() ou ABSPATH? Conte-nos nos comentários: lemos todos.