🛠 2 Formas de obtener la ruta raíz de WordPress

Usted incluye un archivo en functions.php y WordPress no puede encontrarlo. ¿Le suena familiar? La razón casi siempre es una ruta incorrecta hacia la carpeta raíz.

Una ruta fija escrita manualmente como /var/www/html/ se rompe cuando migra a un servidor diferente. Y un ../../wp-content/plugins/ rígidamente incrustado deja de funcionar cuando la estructura de directorios cambia. Afortunadamente, WordPress ofrece dos formas estándar de obtener la ruta absoluta a la raíz del sitio, sin necesidad de adivinar. Ambas incluyen una barra diagonal al final de forma predeterminada, por lo que concatenar subrutas no requiere una / adicional.

Al final de este artículo sabrá exactamente cuándo usar get_home_path() y cuándo usar ABSPATH, y por qué coinciden en algunos proyectos pero devuelven directorios diferentes en otros. Como bono, cubriremos un error común de doble barra diagonal y un escenario para scripts cron externos.

💡 Resumen rápido:

• Abra el functions.php de su tema e incluya wp-admin/includes/file.php, luego llame a get_home_path() para obtener la ruta absoluta con barra diagonal final
• Use la constante ABSPATH de wp-config.php; está disponible globalmente, no requiere inclusión manual y funciona incluso en el front-end
• Con una estructura de directorios no estándar (Bedrock, núcleo reubicado), compare la salida de ambos métodos en un servidor de pruebas; pueden apuntar a carpetas diferentes
• Para plugins y temas distribuidos a través del directorio de WordPress.org, use ABSPATH; es el estándar que funciona de forma fiable en cualquier alojamiento

1. Get_home_path(): la ruta a través de la API de administración

La función get_home_path() está documentada en la documentación oficial de WordPress y devuelve la ruta absoluta del sistema de archivos a la raíz de la instalación, el directorio que contiene wp-admin, wp-includes y wp-content. A diferencia de la codificación manual, no depende del entorno de alojamiento y no se romperá cuando migre.

La principal ventaja: no necesita adivinar si el sitio está desplegado en la raíz del dominio o en un subdirectorio. La función lo determina y devuelve, por ejemplo, /var/www/html/ para una instalación estándar o /home/user/site.com/wordpress/ para un sitio en una subcarpeta. Sin ../../ y sin ediciones manuales de configuración.

El archivo que contiene la función se encuentra en wp-admin/includes/file.php, por lo que get_home_path() no está disponible directamente en un tema o en el front-end. Para usarlo fuera del área de administración, incluya el archivo manualmente primero. Añada el código al functions.php de su tema hijo o mediante un plugin como 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';

Aquí require_once con una ruta construida a partir de ABSPATH carga el archivo de administración solo una vez; una segunda inclusión no causará un conflicto. Después de eso, get_home_path() está disponible en cualquier parte del tema.

Nota: la barra diagonal final ya está incluida en la cadena devuelta. Concatene las subrutas sin una / inicial adicional: $root . 'wp-admin/update.php', no $root . '/wp-admin/update.php'. PHP ignorará silenciosamente una doble barra en la mayoría de los sistemas de archivos, pero algunas comprobaciones estrictas de file_exists() pueden fallar.

2. ABSPATH: la constante directa de wp-config.php

ABSPATH es una constante que WordPress define en wp-config.php durante el arranque. En un archivo estándar se ve así:

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

__DIR__ devuelve el directorio donde reside el propio wp-config.php, y esa es la raíz de WordPress. La constante está disponible globalmente: en temas, plugins, en el front-end, en el administrador, en WP-CLI. No se necesita require_once para cargarla; ya está en memoria desde el momento en que el núcleo arranca.

Su uso es trivial: use ABSPATH en cualquier lugar donde se requiera una ruta absoluta:

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

La barra diagonal final también está presente aquí, con un comportamiento idéntico a get_home_path(). El patrón require_once ABSPATH . 'wp-admin/update.php' funcionará en cualquier alojamiento, en cualquier estructura de directorios, sin ajustes de ruta. Esa es exactamente la razón por la que la mayoría de los plugins en el directorio de WordPress.org usan ABSPATH en lugar de get_home_path(): la constante no requiere inclusión manual de archivos y no depende del contexto de la llamada.

Cuándo get_home_path() y ABSPATH devuelven directorios diferentes

En una instalación estándar de WordPress, ambas construcciones devuelven la misma cadena. Pero hay dos escenarios donde divergen, y si no los conoce, un error puede vivir en su código durante meses.

El núcleo está reubicado de la raíz del documento. Algunos proveedores de alojamiento (Kinsta, WP Engine) y configuraciones personalizadas colocan los archivos del núcleo en un directorio separado, con wp-config.php un nivel por encima. En este caso ABSPATH apunta a la carpeta que contiene wp-config.php, mientras que get_home_path() apunta al subdirectorio con el núcleo. En WordPress StackExchange los desarrolladores comparten un ejemplo real: ABSPATH = /www/site/, mientras que get_home_path() = /www/site/wp/. Una diferencia de un directorio, y require_once falla con un error fatal.

Bedrock y otras estructuras no estándar. En Bedrock de Roots, la raíz del sitio (web/wp/) está separada de la raíz del proyecto, que contiene config/, vendor/ y web/. ABSPATH en Bedrock apunta a web/wp/, mientras que get_home_path() se orienta según la configuración multisitio y la URL de inicio. En la práctica, get_home_path() en Bedrock puede devolver una ruta a web/wp/ que coincida con ABSPATH, pero no confíe en eso; verifíquelo en su proyecto específico.

Conclusión práctica: si está escribiendo un plugin para el directorio de WordPress.org, use ABSPATH; está disponible en todas partes sin inclusiones adicionales. Si está escribiendo código para un sitio específico con una estructura no estándar, verifique ambas constantes en un entorno de pruebas y elija la que apunte a donde realmente necesita. Cinco minutos de comparación en un servidor de pruebas le ahorrarán horas de depuración en producción.

Hay un matiz más con los temas: si su tema se distribuye en ThemeForest o en el directorio de WordPress.org, use siempre ABSPATH; está garantizado que estará definido en el alojamiento de cualquier cliente. get_home_path() puede no funcionar si el tema lo llama antes de que se cargue el área de administración.

El breve video de arriba demuestra visualmente cómo ABSPATH protege los plugins de la ejecución directa y por qué el patrón defined('ABSPATH') or die es un estándar de seguridad para cualquier archivo PHP en el ecosistema de WordPress.

⁉️🤔 Preguntas frecuentes

¿Qué es más rápido: get_home_path() o ABSPATH?

ABSPATH es una constante: su valor se define una vez cuando WordPress carga y se almacena en memoria. get_home_path() es una función que, en la primera llamada, analiza la URL de inicio y calcula la ruta relativa al sistema de archivos. La diferencia de velocidad es ínfima (microsegundos por llamada), pero si la ruta se solicita docenas de veces en una sola petición HTTP, almacene ABSPATH en una variable al inicio de su script y use esa.

¿Necesito incluir manualmente ABSPATH en mis propios archivos?

Si su código se ejecuta en el contexto de WordPress (tema, plugin, manejador AJAX), ABSPATH ya está definido; no necesita incluir nada. La comprobación if (!defined('ABSPATH')) { exit; } al inicio de un archivo PHP independiente en la raíz del sitio es una buena práctica de seguridad: bloquea la ejecución directa del script eludiendo WordPress y protege contra fugas de datos mediante una petición HTTP directa al archivo.

¿Puedo usar ABSPATH en un script cron externo?

Puede, pero con precaución. Si el script reside fuera de la instalación de WordPress, cargue wp-load.php: require_once '/path/to/wp-load.php';. Después de eso, ABSPATH estará disponible. Tenga en cuenta: llamar a wp-load.php directamente carga todo el núcleo y todos los plugins activos, lo cual es excesivo para trabajos cron frecuentes. Para proyectos de alto tráfico, es mejor mover la lógica a un comando de WP-CLI.

¿Devuelve get_home_path() una ruta con doble barra diagonal?

No. La función garantiza devolver una sola barra diagonal final. Una doble barra solo puede aparecer si usted mismo añade una / al inicio de la subruta: get_home_path() . '/wp-admin/'. La forma correcta es sin barra inicial: get_home_path() . 'wp-admin/'. En la mayoría de los sistemas Linux una doble barra es equivalente a una sola, pero no confíe en eso; las comprobaciones de file_exists() en algunas configuraciones pueden devolver false.

¿En qué se diferencia la ruta raíz de la URL de inicio?

La ruta raíz (/var/www/html/) es el sistema de archivos del servidor. La URL de inicio (https://site.com) es la dirección que ve el navegador. Para obtener una URL, use home_url(); para una ruta del sistema de archivos, use get_home_path() o ABSPATH. No las mezcle: require_once espera una ruta del sistema de archivos, wp_remote_get() espera una URL. Si las confunde, obtendrá false de file_exists() o una petición HTTP rota a una ruta local.

Qué usar en su proyecto: la conclusión final

Para la gran mayoría de las tareas, ABSPATH es suficiente. La constante está disponible inmediatamente después de que WordPress carga, no requiere inclusión manual de archivos y funciona de manera idéntica en cualquier alojamiento. Si está escribiendo un plugin o tema para distribución, solo ABSPATH, sin alternativas.

Si administra un sitio con una estructura de directorios no estándar (núcleo reubicado, Bedrock, multisitio con diferentes URLs de inicio), dedique cinco minutos y compare la salida de get_home_path() y ABSPATH en un entorno de pruebas. Una discrepancia de un directorio puede costar horas de depuración en producción.

¿Qué método usa usted, get_home_path() o ABSPATH? Háganoslo saber en los comentarios: leemos todos y cada uno.