mkdir()

Was ist die Funktion mkdir()?

Die Funktion mkdir() ist eine eingebaute PHP-Funktion, die ein neues Verzeichnis im Dateisystem erstellt. Sie greifen darauf zurück, wenn Ihr Skript zur Laufzeit einen Ordner anlegen muss — zum Beispiel zum Speichern hochgeladener Dateien, zum Erzeugen benutzerspezifischer Cache-Verzeichnisse oder zum Einrichten eines Exportordners, bevor Berichte darin geschrieben werden.

Diese Seite behandelt die Signatur der Funktion, jeden Parameter (einschließlich des oft missverstandenen Berechtigungsarguments), das Erstellen verschachtelter Verzeichnisse in einem einzigen Aufruf, den Rückgabewert sowie die Fehlerbehandlung und die häufigsten Stolperfallen.

Hier ist die grundlegende Syntax der Funktion mkdir():

Die PHP-Syntax von mkdir()

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

Parameter

Hinweis zu Berechtigungen und umask

Der übergebene $permissions-Wert wird nicht unverändert angewendet. Das Betriebssystem subtrahiert die Prozess-umask davon. Mit der üblichen umask 022 erzeugt beispielsweise mkdir($dir, 0777) ein Verzeichnis mit dem Modus 0755, nicht 0777. Übergeben Sie deshalb stets den gewünschten Modus und gehen Sie nicht davon aus, dass 0777 „weltweit beschreibbar" bedeutet — in der Regel ist das nicht der Fall.

Aus Sicherheitsgründen ist 0755 (Eigentümer kann lesen/schreiben/ausführen, alle anderen können lesen/ausführen) dem Standard 0777 vorzuziehen. Wenn Sie einen exakten Modus unabhängig von der umask benötigen, rufen Sie chmod() nach dem Erstellen des Verzeichnisses auf.

Wie verwendet man die Funktion mkdir()?

Die Verwendung der Funktion mkdir() ist unkompliziert. Hier sind die Schritte:

1. Geben Sie den Pfad des Verzeichnisses an, das Sie erstellen möchten.
2. Rufen Sie die Funktion mkdir() auf und übergeben Sie den Verzeichnispfad als ersten Parameter, einen optionalen Berechtigungsmodus als zweiten Parameter und ein boolesches Flag als dritten Parameter, um bei Bedarf übergeordnete Verzeichnisse zu erstellen.

Hier ist ein Beispiel-Code-Ausschnitt, der zeigt, wie die Funktion mkdir() verwendet wird:

Wie verwendet man die Funktion 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!";
}

In diesem Beispiel verwenden wir is_dir(), um zu prüfen, ob das Ziel bereits existiert. Wir geben einen sichereren Berechtigungsmodus (0755) an und übergeben true als drittes Argument, um die rekursive Erstellung zu aktivieren. Da die Funktion mkdir() einen booleschen Wert zurückgibt, schließen wir den Aufruf in eine if-Anweisung ein, um Erfolg oder Misserfolg sauber zu behandeln. Existiert das Verzeichnis nicht, versuchen wir es zu erstellen und geben eine Erfolgs- oder Fehlermeldung aus. Wenn es bereits existiert, geben wir eine entsprechende Meldung aus.

Verschachtelte Verzeichnisse erstellen

Ohne das rekursive Flag kann mkdir() nur das letzte Segment eines Pfades erstellen — alle übergeordneten Verzeichnisse müssen bereits vorhanden sein. Durch Übergabe von true als drittem Argument wird PHP angewiesen, die gesamte Kette auf einmal zu erstellen:

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

Rückgabewert und Fehlerbehandlung

mkdir() gibt bei Erfolg true und bei Misserfolg false zurück. Bei einem Fehler wird zusätzlich eine E_WARNING ausgelöst — zum Beispiel wenn das übergeordnete Verzeichnis fehlt, der Pfad bereits existiert oder der Prozess keine Schreibberechtigung hat.

Es gibt zwei saubere Wege, mit dieser Warnung umzugehen:

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

Vermeiden Sie die Verwendung von @ allein ohne Überprüfung des Rückgabewertes — das stille Unterdrücken der Warnung macht Fehler unsichtbar.

Häufige Stolperfallen

• Das Verzeichnis existiert bereits. mkdir() gibt false zurück und gibt eine Warnung aus. Prüfen Sie immer zuerst mit is_dir(), oder verwenden Sie das oben beschriebene rekursive Erstellungsmuster.
• Berechtigungen werden durch die umask gefiltert. Wie oben erläutert, wird der übergebene Modus maskiert. Verwenden Sie chmod() für einen exakten Modus.
• Relative Pfade hängen vom Arbeitsverzeichnis ab. Ein relativer Pfad wird gegen das aktuelle Verzeichnis des Skripts aufgelöst, das vom Speicherort der Datei abweichen kann. Verwenden Sie im Zweifelsfall einen absoluten Pfad (z. B. __DIR__ . '/uploads').
• Windows ignoriert das Berechtigungsargument vollständig — es hat dort keine Wirkung.

Verwandte Funktionen

• rmdir() — ein leeres Verzeichnis entfernen (das Gegenstück zu mkdir()).
• scandir() — den Inhalt eines Verzeichnisses auflisten.
• chmod() — die Berechtigungen eines Verzeichnisses nach der Erstellung ändern.
• fopen() — eine Datei öffnen oder erstellen, sobald das Verzeichnis existiert.

Fazit

Die Funktion mkdir() ist ein nützliches Werkzeug in PHP zum Erstellen neuer Verzeichnisse im Dateisystem. Die wichtigsten Dinge zu beachten sind: Übergeben Sie einen expliziten, sicheren Berechtigungsmodus (wie 0755) anstatt sich auf den Standard 0777 zu verlassen, verwenden Sie das rekursive Flag, wenn übergeordnete Verzeichnisse möglicherweise fehlen, und überprüfen Sie immer den booleschen Rückgabewert, damit Fehler nicht unbemerkt bleiben. Mit diesen Gewohnheiten wird mkdir() zu einem zuverlässigen Baustein für jedes Skript, das mit dem Dateisystem arbeitet.

Übung