mkdir()

¿Qué es la función mkdir()?

La función mkdir() es una función integrada de PHP que crea un nuevo directorio en el sistema de archivos. Se utiliza cuando el script necesita crear una carpeta en tiempo de ejecución — por ejemplo, para almacenar archivos subidos, generar directorios de caché por usuario, o crear una carpeta de exportación antes de escribir informes en ella.

Esta página cubre la firma de la función, cada parámetro (incluido el argumento de permisos que suele generar confusión), cómo crear directorios anidados en una sola llamada, el valor de retorno y cómo manejar errores, y los errores comunes que suelen cometerse.

Aquí está la sintaxis básica de la función mkdir():

La sintaxis PHP de mkdir()

mkdir(string $directory, int $permissions = 0777, bool $recursive = false, ?resource $context = null): bool

Parámetros

Una nota sobre permisos y umask

El valor de $permissions que se pasa no se aplica literalmente. El sistema operativo resta el umask del proceso. Por ejemplo, con el umask común 022, llamar a mkdir($dir, 0777) produce un directorio con modo 0755, no 0777. Por este motivo, pasa siempre el modo que realmente deseas y no asumas que 0777 significa "escritura para todos" — generalmente no es así.

Por seguridad, prefiere 0755 (el propietario puede leer/escribir/ejecutar, los demás pueden leer/ejecutar) sobre el predeterminado 0777. Si necesitas un modo exacto independientemente del umask, llama a chmod() después de crear el directorio.

¿Cómo usar la función mkdir()?

Usar la función mkdir() es sencillo. Estos son los pasos a seguir:

1. Especifica la ruta del directorio que deseas crear.
2. Llama a la función mkdir(), pasando la ruta del directorio como primer parámetro, un modo de permisos opcional como segundo parámetro, y un indicador booleano como tercer parámetro para crear directorios padre si es necesario.

Aquí hay un ejemplo de código que demuestra cómo usar la función mkdir():

¿Cómo usar la función mkdir()?

<?php

$dir = '/path/to/new/directory';
// 0755 is recommended for security (owner: rwx, others: rx)
$permissions = 0755;
if (!is_dir($dir)) {
    if (mkdir($dir, $permissions, true)) {
        echo "Directory created successfully!";
    } else {
        echo "Failed to create directory.";
    }
} else {
    echo "Directory already exists!";
}

En este ejemplo, usamos is_dir() para comprobar si el destino ya existe. Especificamos un modo de permisos más seguro (0755) y pasamos true como tercer argumento para habilitar la creación recursiva. La función mkdir() devuelve un valor booleano, por lo que envolvemos la llamada en una sentencia if para manejar el éxito o el fracaso de forma elegante. Si el directorio no existe, intentamos crearlo e imprimimos un mensaje de éxito o error. Si ya existe, imprimimos un mensaje indicándolo.

Creación de directorios anidados

Sin el indicador recursivo, mkdir() solo puede crear el último segmento de una ruta — todos los padres deben existir previamente. Pasar true como tercer argumento le indica a PHP que cree toda la cadena de una vez:

<?php

// Fails if "cache" or "cache/images" don't already exist:
// mkdir('cache/images/thumbs');           // Warning + returns false

// Works — creates cache, cache/images and cache/images/thumbs as needed:
if (mkdir('cache/images/thumbs', 0755, true)) {
    echo 'Nested directories created.';
}

Valor de retorno y manejo de errores

mkdir() devuelve true en caso de éxito y false en caso de fallo. En caso de fallo, también genera un E_WARNING — por ejemplo, cuando falta el directorio padre, la ruta ya existe, o el proceso no tiene permiso de escritura.

Hay dos formas limpias de gestionar esa advertencia:

<?php

// 1. Guard with is_dir() so you never try to recreate an existing folder.
$dir = 'uploads';
if (!is_dir($dir) && !mkdir($dir, 0755, true) && !is_dir($dir)) {
    // The second is_dir() guards against a race where another
    // process created the directory between our two checks.
    throw new RuntimeException("Directory \"$dir\" could not be created");
}

// 2. Suppress the warning with @ only if you immediately check the result.
if (!@mkdir($dir, 0755) && !is_dir($dir)) {
    echo 'Could not create directory.';
}

Evita usar @ solo sin comprobar el valor de retorno — ignorar silenciosamente la advertencia hace que los fallos sean invisibles.

Errores comunes

• El directorio ya existe. mkdir() devuelve false y emite una advertencia. Comprueba siempre con is_dir() antes, o utiliza el patrón de creación recursiva mostrado arriba.
• Los permisos son filtrados por el umask. Como se explicó anteriormente, el modo que se pasa es enmascarado. Usa chmod() para un modo exacto.
• Las rutas relativas dependen del directorio de trabajo. Una ruta relativa se resuelve respecto al directorio actual del script, que puede diferir de la ubicación del archivo. Usa una ruta absoluta (por ejemplo, __DIR__ . '/uploads') cuando tengas dudas.
• Windows ignora el argumento de permisos por completo — no tiene ningún efecto allí.

Funciones relacionadas

• rmdir() — elimina un directorio vacío (la contraparte de mkdir()).
• scandir() — lista el contenido de un directorio.
• chmod() — cambia los permisos de un directorio después de su creación.
• fopen() — abre o crea un archivo una vez que el directorio existe.

Conclusión

La función mkdir() es una herramienta útil en PHP para crear nuevos directorios en un sistema de archivos. Los aspectos clave a recordar son: pasar un modo de permisos explícito y seguro (como 0755) en lugar de depender del valor predeterminado 0777, usar el indicador recursivo cuando los directorios padre puedan faltar, y comprobar siempre el valor de retorno booleano para que los fallos no pasen desapercibidos. Con estos hábitos, mkdir() se convierte en un bloque de construcción fiable para cualquier script que trabaje con el sistema de archivos.

Práctica