🛠 2 Modi per ottenere il percorso root di WordPress

Includi un file in functions.php e WordPress non lo trova. Ti suona familiare? Il motivo è quasi sempre un percorso errato verso la cartella root.

Un percorso cablato manualmente come /var/www/html/ si rompe quando sposti il sito su un server diverso. E un rigido ../../wp-content/plugins/ smette di funzionare quando la struttura delle directory cambia. Per fortuna, WordPress offre due metodi standard per ottenere il percorso assoluto della root del sito, senza tentativi. Entrambi includono già uno slash finale, quindi concatenare i sottopercorsi non richiede un / aggiuntivo.

Alla fine di questo post saprai esattamente quando usare get_home_path() e quando usare ABSPATH, e perché in alcuni progetti coincidono ma in altri restituiscono directory diverse. Come bonus, vedremo un errore comune legato al doppio slash e uno scenario per gli script cron esterni.

💡 Panoramica rapida:

• Apri il functions.php del tuo tema e includi wp-admin/includes/file.php, poi chiama get_home_path() per ottenere il percorso assoluto con slash finale
• Usa la costante ABSPATH da wp-config.php; è disponibile globalmente, non richiede inclusioni manuali e funziona anche nel front end
• Con una struttura di directory non standard (Bedrock, core rilocato), confronta l'output di entrambi i metodi su un server di test; potrebbero puntare a cartelle diverse
• Per plugin e temi distribuiti tramite la directory di WordPress.org, usa ABSPATH; è lo standard che funziona in modo affidabile su qualsiasi hosting

1. Get_home_path(): il percorso tramite l'API di amministrazione

La funzione get_home_path() è documentata nella documentazione ufficiale di WordPress e restituisce il percorso assoluto nel filesystem della root di installazione, la directory che contiene wp-admin, wp-includes e wp-content. A differenza di un percorso cablato manualmente, non dipende dall'ambiente di hosting e non si rompe quando migri il sito.

Il vantaggio principale: non devi indovinare se il sito è deployato nella root del dominio o in una sottodirectory. La funzione lo determina e restituisce, per esempio, /var/www/html/ per un'installazione standard o /home/user/site.com/wordpress/ per un sito in una sottocartella. Niente ../../ e nessuna modifica manuale alla configurazione.

Il file che contiene la funzione si trova in wp-admin/includes/file.php, quindi get_home_path() non è disponibile direttamente in un tema o nel front end. Per usarla fuori dall'area di amministrazione, includi prima il file manualmente. Aggiungi il codice al functions.php del tuo tema child o tramite un plugin come 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';

Qui require_once con un percorso costruito a partire da ABSPATH carica il file di amministrazione una sola volta; una seconda inclusione non causerà conflitti. Dopodiché, get_home_path() è disponibile ovunque nel tema.

Nota: lo slash finale è già incluso nella stringa restituita. Concatena i sottopercorsi senza uno / iniziale aggiuntivo: $root . 'wp-admin/update.php', non $root . '/wp-admin/update.php'. PHP ignorerà silenziosamente un doppio slash sulla maggior parte dei filesystem, ma alcuni controlli rigorosi di file_exists() potrebbero fallire.

2. ABSPATH: la costante direttamente da wp-config.php

ABSPATH è una costante che WordPress definisce in wp-config.php durante l'avvio. In un file standard appare così:

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

__DIR__ restituisce la directory in cui risiede wp-config.php stesso, che è la root di WordPress. La costante è disponibile globalmente: nei temi, nei plugin, nel front end, nell'admin, in WP-CLI. Non serve require_once per caricarla; è già in memoria dal momento in cui il core si avvia.

L'uso è banale: usa ABSPATH ovunque sia richiesto un percorso assoluto:

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';

Anche qui lo slash finale è presente, comportamento identico a get_home_path(). Il pattern require_once ABSPATH . 'wp-admin/update.php' funzionerà su qualsiasi hosting, in qualsiasi struttura di directory, senza alcun aggiustamento del percorso. È esattamente il motivo per cui la maggior parte dei plugin nella directory di WordPress.org usa ABSPATH anziché get_home_path(): la costante non richiede inclusioni manuali di file e non dipende dal contesto di chiamata.

Quando get_home_path() e ABSPATH restituiscono directory diverse

In un'installazione standard di WordPress, entrambi i costrutti restituiscono la stessa stringa. Ma ci sono due scenari in cui divergono e, se non ne sei consapevole, un bug può rimanere nel tuo codice per mesi.

Il core è rilocato rispetto alla document root. Alcuni provider di hosting (Kinsta, WP Engine) e configurazioni personalizzate collocano i file del core in una directory separata, con wp-config.php un livello sopra. In questo caso ABSPATH punta alla cartella che contiene wp-config.php, mentre get_home_path() punta alla sottodirectory con il core. Su WordPress StackExchange gli sviluppatori condividono un esempio reale: ABSPATH = /www/site/, mentre get_home_path() = /www/site/wp/. Una differenza di una directory, e require_once fallisce con un errore fatale.

Bedrock e altre strutture non standard. In Bedrock di Roots, la root del sito (web/wp/) è separata dalla root del progetto, che contiene config/, vendor/ e web/. ABSPATH in Bedrock punta a web/wp/, mentre get_home_path() si orienta in base alle impostazioni multisite e all'URL home. In pratica, get_home_path() in Bedrock potrebbe restituire un percorso verso web/wp/ che coincide con ABSPATH, ma non farci affidamento; verifica sul tuo progetto specifico.

Consiglio pratico: se stai scrivendo un plugin per la directory di WordPress.org, usa ABSPATH; è disponibile ovunque senza inclusioni extra. Se stai scrivendo codice per un sito specifico con una struttura non standard, controlla entrambe le costanti in un ambiente di test e scegli quella che punta dove ti serve effettivamente. Cinque minuti di confronto su un server di test ti faranno risparmiare ore di debug in produzione.

C'è un'altra sfumatura con i temi: se il tuo tema è distribuito su ThemeForest o nella directory di WordPress.org, usa sempre ABSPATH; è garantito che sia definito su qualsiasi hosting dei clienti. get_home_path() potrebbe non funzionare se il tema la chiama prima che l'area di amministrazione venga caricata.

Il breve video qui sopra mostra visivamente come ABSPATH protegge i plugin dall'esecuzione diretta e perché il pattern defined('ABSPATH') or die è uno standard di sicurezza per qualsiasi file PHP nell'ecosistema WordPress.

⁉️🤔 Domande frequenti

Qual è più veloce: get_home_path() o ABSPATH?

ABSPATH è una costante: il suo valore è definito una volta quando WordPress si carica ed è memorizzato in memoria. get_home_path() è una funzione che, alla prima chiamata, analizza l'URL home e calcola il percorso relativo al filesystem. La differenza di velocità è trascurabile (microsecondi per chiamata), ma se il percorso viene richiesto decine di volte in una singola richiesta HTTP, memorizza ABSPATH in una variabile all'inizio del tuo script e usa quella.

Devo includere manualmente ABSPATH nei miei file?

Se il tuo codice viene eseguito nel contesto di WordPress (tema, plugin, gestore AJAX), ABSPATH è già definito; non devi includere nulla. Il controllo if (!defined('ABSPATH')) { exit; } all'inizio di un file PHP standalone nella root del sito è una buona pratica di sicurezza: blocca l'esecuzione diretta dello script bypassando WordPress e protegge da fughe di dati tramite una richiesta HTTP diretta al file.

Posso usare ABSPATH in uno script cron esterno?

Puoi, ma con cautela. Se lo script risiede fuori dall'installazione di WordPress, carica wp-load.php: require_once '/path/to/wp-load.php';. Dopodiché, ABSPATH diventa disponibile. Tieni presente: chiamare wp-load.php direttamente carica l'intero core e tutti i plugin attivi, il che è eccessivo per job cron frequenti. Per progetti ad alto traffico, è meglio spostare la logica in un comando WP-CLI.

get_home_path() restituisce un percorso con un doppio slash?

No. La funzione è garantita per restituire un singolo slash finale. Un doppio slash può apparire solo se aggiungi tu un / all'inizio del sottopercorso: get_home_path() . '/wp-admin/'. Il modo corretto è senza slash iniziale: get_home_path() . 'wp-admin/'. Sulla maggior parte dei sistemi Linux un doppio slash è equivalente a uno singolo, ma non farci affidamento; i controlli di file_exists() su alcune configurazioni potrebbero restituire false.

In cosa differisce il percorso root dall'URL home?

Il percorso root (/var/www/html/) è il filesystem del server. L'URL home (https://site.com) è l'indirizzo che vede il browser. Per ottenere un URL, usa home_url(); per un percorso nel filesystem, usa get_home_path() o ABSPATH. Non confonderli: require_once si aspetta un percorso nel filesystem, wp_remote_get() si aspetta un URL. Se li scambi, otterrai o false da file_exists() o una richiesta HTTP interrotta verso un percorso locale.

Cosa usare nel tuo progetto: in conclusione

Per la stragrande maggioranza dei compiti, ABSPATH è sufficiente. La costante è disponibile immediatamente dopo il caricamento di WordPress, non richiede inclusioni manuali di file e funziona in modo identico su qualsiasi hosting. Se stai scrivendo un plugin o un tema per la distribuzione, solo ABSPATH, nessuna alternativa.

Se amministri un sito con una struttura di directory non standard (core rilocato, Bedrock, multisite con URL home diversi), dedica cinque minuti e confronta l'output di get_home_path() e ABSPATH in un ambiente di test. Una discrepanza di una directory può costare ore di debug in produzione.

Quale metodo usi, get_home_path() o ABSPATH? Faccelo sapere nei commenti: li leggiamo tutti.