dirname()

Función PHP dirname()

La función dirname() devuelve la porción del directorio padre de una ruta. Dado el path completo a un archivo o directorio, elimina el componente final y te entrega el directorio que lo contiene. Esta página cubre la sintaxis, el parámetro $levels, los casos especiales y en qué se diferencia dirname() de otras funciones de rutas relacionadas.

Es una operación puramente de string: dirname() analiza el texto de la ruta que le pasas. No accede al sistema de archivos, por lo que la ruta no tiene que apuntar a un archivo que exista realmente.

Sintaxis

dirname(string $path, int $levels = 1): string

• $path — la ruta sobre la que operar (obligatorio).
• $levels — cuántos niveles de directorio subir. Por defecto es 1. Disponible desde PHP 7.0; debe ser 1 o mayor.

Devuelve el directorio padre de $path como un string.

Parámetros

Ejemplos

Obtener el directorio de un archivo

Esto recupera el directorio que contiene example.txt:

Salida:

/home/user1

Obtener el padre de un directorio

Una barra diagonal al final se trata como el fin del nombre de directorio, por lo que dirname() sigue devolviendo el padre:

Salida:

/home/user1

Subir varios niveles con $levels

Pasa un segundo argumento para subir más en el árbol en una sola llamada:

<?php

echo dirname("/usr/local/lib", 2);

Salida:

/usr

Esto equivale a dirname(dirname("/usr/local/lib")), pero resulta más claro cuando necesitas subir varios niveles.

Casos especiales a tener en cuenta

dirname() tiene algunos resultados que sorprenden la primera vez:

<?php

echo dirname("example.txt"), "\n";   // "."  — no directory part, so current dir
echo dirname("/"), "\n";             // "/"  — root has no parent
echo dirname(""), "\n";              // "."

• Una ruta sin componente de directorio devuelve . (el directorio actual), no un string vacío.
• La ruta raíz se devuelve a sí misma.
• En Windows, tanto / como \ se aceptan como separadores de directorio.

dirname() vs. funciones relacionadas

• basename() — el opuesto de dirname(): devuelve el último componente (el nombre del archivo o carpeta) en lugar del directorio padre.
• pathinfo() — devuelve un array con dirname, basename, extension y filename de una sola vez, lo cual es útil cuando necesitas más de un dato.
• realpath() — resuelve una ruta contra el sistema de archivos real (siguiendo enlaces simbólicos y ..), a diferencia de dirname(), que solo trabaja con texto.

Un patrón habitual es construir rutas relativas al archivo actual:

<?php

// Load config that sits one directory above this script.
require dirname(__DIR__) . "/config.php";

Conclusión

dirname() extrae el directorio padre de una ruta como una operación simple sobre strings. Recuerda que nunca accede al sistema de archivos, que una ruta sin directorio devuelve ., y que el argumento $levels te permite subir varios directorios en una sola llamada. Para la parte complementaria del nombre de archivo, usa basename(); para obtenerlo todo a la vez, usa pathinfo().

Práctica