mkdir()

Qu'est-ce que la fonction mkdir() ?

La fonction mkdir() est une fonction PHP intégrée qui crée un nouveau répertoire sur le système de fichiers. On y fait appel chaque fois qu'un script doit créer un dossier à l'exécution — par exemple pour stocker des fichiers téléversés, générer des répertoires de cache par utilisateur ou préparer un dossier d'export avant d'y écrire des rapports.

Cette page couvre la signature de la fonction, chacun de ses paramètres (y compris l'argument de permissions souvent mal compris), la création de répertoires imbriqués en un seul appel, la valeur de retour et la gestion des erreurs, ainsi que les pièges courants.

Voici la syntaxe de base de la fonction mkdir() :

La syntaxe PHP de mkdir()

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

Paramètres

Note sur les permissions et l'umask

La valeur $permissions que vous passez n'est pas appliquée telle quelle. Le système d'exploitation soustrait l'umask du processus. Par exemple, avec l'umask courant 022, appeler mkdir($dir, 0777) produit un répertoire avec le mode 0755, pas 0777. Pour cette raison, passez toujours le mode souhaité et ne supposez pas que 0777 signifie « accessible en écriture par tous » — ce n'est généralement pas le cas.

Pour la sécurité, préférez 0755 (le propriétaire peut lire/écrire/exécuter, les autres peuvent lire/exécuter) à la valeur par défaut 0777. Si vous avez besoin d'un mode exact indépendamment de l'umask, appelez chmod() après la création du répertoire.

Comment utiliser la fonction mkdir() ?

L'utilisation de la fonction mkdir() est simple. Voici les étapes à suivre :

1. Spécifiez le chemin du répertoire que vous souhaitez créer.
2. Appelez la fonction mkdir() en lui passant le chemin du répertoire comme premier paramètre, un mode de permissions optionnel comme second paramètre, et un booléen comme troisième paramètre pour créer les répertoires parents si nécessaire.

Voici un exemple de code illustrant l'utilisation de la fonction mkdir() :

Comment utiliser la fonction 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!";
}

Dans cet exemple, nous utilisons is_dir() pour vérifier si la cible existe déjà. Nous spécifions un mode de permissions plus sécurisé (0755) et passons true comme troisième argument pour activer la création récursive. La fonction mkdir() retourne un booléen, nous enveloppons donc l'appel dans un if pour gérer le succès ou l'échec proprement. Si le répertoire n'existe pas, nous tentons de le créer et affichons un message de succès ou d'échec. S'il existe déjà, nous affichons un message indiquant son existence.

Créer des répertoires imbriqués

Sans l'indicateur récursif, mkdir() ne peut créer que le dernier segment d'un chemin — tous les parents doivent déjà exister. Passer true comme troisième argument indique à PHP de créer toute la chaîne en une seule fois :

<?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.';
}

Valeur de retour et gestion des erreurs

mkdir() retourne true en cas de succès et false en cas d'échec. En cas d'échec, elle émet également un E_WARNING — par exemple lorsque le répertoire parent est manquant, que le chemin existe déjà ou que le processus n'a pas la permission d'écriture.

Il existe deux façons propres de gérer cet avertissement :

<?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.';
}

Évitez d'utiliser @ seul sans vérifier la valeur de retour — ignorer silencieusement l'avertissement rend les échecs invisibles.

Pièges courants

• Le répertoire existe déjà. mkdir() retourne false et émet un avertissement. Vérifiez toujours avec is_dir() au préalable, ou utilisez l'idiome de création récursive décrit plus haut.
• Les permissions sont filtrées par l'umask. Comme indiqué plus haut, le mode passé est masqué. Utilisez chmod() pour un mode exact.
• Les chemins relatifs dépendent du répertoire de travail. Un chemin relatif est résolu par rapport au répertoire courant du script, qui peut différer de l'emplacement du fichier. Utilisez un chemin absolu (ex. __DIR__ . '/uploads') en cas de doute.
• Windows ignore entièrement l'argument de permissions — c'est une opération sans effet sur ce système.

Fonctions associées

• rmdir() — supprime un répertoire vide (le pendant de mkdir()).
• scandir() — liste le contenu d'un répertoire.
• chmod() — modifie les permissions d'un répertoire après sa création.
• fopen() — ouvre ou crée un fichier une fois le répertoire créé.

Conclusion

La fonction mkdir() est un outil utile en PHP pour créer de nouveaux répertoires sur un système de fichiers. Les points essentiels à retenir sont : passer un mode de permissions explicite et sécurisé (comme 0755) plutôt que de se fier à la valeur par défaut 0777, utiliser l'indicateur récursif lorsque les répertoires parents peuvent être absents, et toujours vérifier la valeur de retour booléenne pour que les échecs ne passent pas inaperçus. Avec ces bonnes pratiques, mkdir() devient un élément fiable pour tout script travaillant avec le système de fichiers.

Pratique