🛠 2 Façons d'obtenir le chemin racine de WordPress

Vous incluez un fichier dans functions.php, et WordPress ne le trouve pas. Cela vous semble familier? La raison en est presque toujours un chemin incorrect vers le dossier racine.

Un chemin codé en dur manuellement comme /var/www/html/ ne fonctionne plus lorsque vous migrez vers un autre serveur. Et un ../../wp-content/plugins/ rigidement intégré cesse de fonctionner lorsque la structure des répertoires change. Heureusement, WordPress propose deux méthodes standard pour obtenir le chemin absolu vers la racine du site, sans approximation. Les deux incluent un slash final par défaut, donc la concaténation des sous-chemins ne nécessite pas de / supplémentaire.

À la fin de cet article, vous saurez exactement quand utiliser get_home_path() et quand utiliser ABSPATH, et pourquoi ils correspondent dans certains projets mais renvoient des répertoires différents dans d'autres. En bonus, nous aborderons une erreur courante de double slash et un scénario pour les scripts cron externes.

💡 Aperçu rapide:

• Ouvrez le functions.php de votre thème et incluez wp-admin/includes/file.php, puis appelez get_home_path() pour obtenir le chemin absolu avec un slash final
• Utilisez la constante ABSPATH de wp-config.php; elle est disponible globalement, ne nécessite aucune inclusion manuelle et fonctionne même en front-end
• Avec une structure de répertoires non standard (Bedrock, cœur déplacé), comparez la sortie des deux méthodes sur un serveur de test; elles peuvent pointer vers des dossiers différents
• Pour les plugins et thèmes distribués via le répertoire WordPress.org, utilisez ABSPATH; c'est la norme qui fonctionne de manière fiable sur tout hébergement

1. Get_home_path(): le chemin via l'API d'administration

La fonction get_home_path() est documentée dans la documentation officielle de WordPress et renvoie le chemin absolu du système de fichiers vers la racine de l'installation, le répertoire qui contient wp-admin, wp-includes et wp-content. Contrairement à un codage en dur manuel, elle ne dépend pas de l'environnement d'hébergement et ne cassera pas lors d'une migration.

Le principal avantage: vous n'avez pas besoin de deviner si le site est déployé à la racine du domaine ou dans un sous-répertoire. La fonction le détermine et renvoie, par exemple, /var/www/html/ pour une installation standard ou /home/user/site.com/wordpress/ pour un site dans un sous-dossier. Pas de ../../ ni de modifications manuelles de configuration.

Le fichier contenant la fonction se trouve dans wp-admin/includes/file.php, donc get_home_path() n'est pas disponible directement dans un thème ou en front-end. Pour l'utiliser en dehors de la zone d'administration, incluez d'abord le fichier manuellement. Ajoutez le code au functions.php de votre thème enfant ou via un plugin comme 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';

Ici, require_once avec un chemin construit à partir de ABSPATH charge le fichier d'administration une seule fois; une seconde inclusion ne causera pas de conflit. Après cela, get_home_path() est disponible partout dans le thème.

Remarque: le slash final est déjà inclus dans la chaîne renvoyée. Concaténez les sous-chemins sans / initial supplémentaire: $root . 'wp-admin/update.php', et non $root . '/wp-admin/update.php'. PHP ignorera silencieusement un double slash sur la plupart des systèmes de fichiers, mais certaines vérifications strictes de file_exists() peuvent échouer.

2. ABSPATH: la constante directement issue de wp-config.php

ABSPATH est une constante que WordPress définit dans wp-config.php lors du démarrage. Dans un fichier standard, elle ressemble à ceci:

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

__DIR__ renvoie le répertoire où réside wp-config.php lui-même, et c'est la racine de WordPress. La constante est disponible globalement: dans les thèmes, les plugins, en front-end, dans l'administration, dans WP-CLI. Aucun require_once nécessaire pour la charger; elle est déjà en mémoire dès le démarrage du cœur.

L'utilisation est triviale: utilisez ABSPATH partout où un chemin absolu est requis:

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

Le slash final est également présent ici, comportement identique à get_home_path(). Le modèle require_once ABSPATH . 'wp-admin/update.php' fonctionnera sur tout hébergement, dans toute structure de répertoires, sans aucun ajustement de chemin. C'est exactement pourquoi la plupart des plugins du répertoire WordPress.org utilisent ABSPATH plutôt que get_home_path(): la constante ne nécessite aucune inclusion manuelle de fichier et ne dépend pas du contexte d'appel.

Quand get_home_path() et ABSPATH renvoient des répertoires différents

Dans une installation WordPress standard, les deux constructions renvoient la même chaîne. Mais il existe deux scénarios où elles divergent, et si vous n'en êtes pas conscient, un bug peut rester dans votre code pendant des mois.

Le cœur est déplacé de la racine du document. Certains hébergeurs (Kinsta, WP Engine) et configurations personnalisées placent les fichiers du cœur dans un répertoire séparé, avec wp-config.php un niveau au-dessus. Dans ce cas, ABSPATH pointe vers le dossier contenant wp-config.php, tandis que get_home_path() pointe vers le sous-répertoire contenant le cœur. Sur WordPress StackExchange, des développeurs partagent un exemple concret: ABSPATH = /www/site/, tandis que get_home_path() = /www/site/wp/. Une différence d'un répertoire, et require_once échoue avec une erreur fatale.

Bedrock et autres structures non standard. Dans Bedrock de Roots, la racine du site (web/wp/) est séparée de la racine du projet, qui contient config/, vendor/ et web/. ABSPATH dans Bedrock pointe vers web/wp/, tandis que get_home_path() s'oriente en fonction des paramètres multisite et de l'URL de domicile. En pratique, get_home_path() dans Bedrock peut renvoyer un chemin vers web/wp/ qui correspond à ABSPATH, mais ne vous y fiez pas; vérifiez sur votre projet spécifique.

Enseignement pratique: si vous écrivez un plugin pour le répertoire WordPress.org, utilisez ABSPATH; elle est disponible partout sans inclusions supplémentaires. Si vous écrivez du code pour un site spécifique avec une structure non standard, vérifiez les deux constantes dans un environnement de test et choisissez celle qui pointe là où vous en avez réellement besoin. Cinq minutes de comparaison sur un serveur de test vous feront gagner des heures de débogage en production.

Il y a une nuance supplémentaire avec les thèmes: si votre thème est distribué sur ThemeForest ou dans le répertoire WordPress.org, utilisez toujours ABSPATH; elle est garantie d'être définie sur l'hébergement de tout client. get_home_path() peut ne pas fonctionner si le thème l'appelle avant le chargement de la zone d'administration.

La courte vidéo ci-dessus montre visuellement comment ABSPATH protège les plugins contre l'exécution directe et pourquoi le modèle defined('ABSPATH') or die est une norme de sécurité pour tout fichier PHP dans l'écosystème WordPress.

⁉️🤔 Questions fréquentes

Qu'est-ce qui est le plus rapide: get_home_path() ou ABSPATH?

ABSPATH est une constante: sa valeur est définie une fois au chargement de WordPress et stockée en mémoire. get_home_path() est une fonction qui, au premier appel, analyse l'URL de domicile et calcule le chemin relatif au système de fichiers. La différence de vitesse est infime (microsecondes par appel), mais si le chemin est demandé des dizaines de fois dans une seule requête HTTP, stockez ABSPATH dans une variable en haut de votre script et utilisez-la.

Dois-je inclure manuellement ABSPATH dans mes propres fichiers?

Si votre code s'exécute dans le contexte WordPress (thème, plugin, gestionnaire AJAX), ABSPATH est déjà définie; vous n'avez rien à inclure. La vérification if (!defined('ABSPATH')) { exit; } en haut d'un fichier PHP autonome à la racine du site est une bonne pratique de sécurité: elle bloque l'exécution directe du script en contournant WordPress et protège contre les fuites de données via une requête HTTP directe vers le fichier.

Puis-je utiliser ABSPATH dans un script cron externe?

Vous le pouvez, mais avec prudence. Si le script réside en dehors de l'installation WordPress, chargez wp-load.php: require_once '/path/to/wp-load.php';. Après cela, ABSPATH devient disponible. Gardez à l'esprit: appeler wp-load.php directement charge tout le cœur et tous les plugins actifs, ce qui est excessif pour des tâches cron fréquentes. Pour les projets à fort trafic, il est préférable de déplacer la logique dans une commande WP-CLI.

Est-ce que get_home_path() renvoie un chemin avec un double slash?

Non. La fonction est garantie de renvoyer un seul slash final. Un double slash ne peut apparaître que si vous ajoutez vous-même un / au début du sous-chemin: get_home_path() . '/wp-admin/'. La manière correcte est sans slash initial: get_home_path() . 'wp-admin/'. Sur la plupart des systèmes Linux, un double slash équivaut à un simple, mais ne vous y fiez pas; les vérifications file_exists() sur certaines configurations peuvent renvoyer false.

En quoi le chemin racine diffère-t-il de l'URL de domicile?

Le chemin racine (/var/www/html/) est le système de fichiers du serveur. L'URL de domicile (https://site.com) est l'adresse que voit le navigateur. Pour obtenir une URL, utilisez home_url(); pour un chemin système, utilisez get_home_path() ou ABSPATH. Ne les confondez pas: require_once attend un chemin système, wp_remote_get() attend une URL. Si vous les inversez, vous obtiendrez soit false de file_exists(), soit une requête HTTP cassée vers un chemin local.

Que choisir pour votre projet: l'essentiel

Pour la grande majorité des tâches, ABSPATH est suffisant. La constante est disponible immédiatement après le chargement de WordPress, ne nécessite aucune inclusion manuelle de fichier et fonctionne de manière identique sur tout hébergement. Si vous écrivez un plugin ou un thème destiné à la distribution, ABSPATH uniquement, pas d'alternative.

Si vous administrez un site avec une structure de répertoires non standard (cœur déplacé, Bedrock, multisite avec des URL de domicile différentes), prenez cinq minutes et comparez la sortie de get_home_path() et ABSPATH dans un environnement de test. Un écart d'un seul répertoire peut coûter des heures de débogage en production.

Quelle méthode utilisez-vous, get_home_path() ou ABSPATH? Faites-le nous savoir dans les commentaires: nous les lisons tous.