move_uploaded_file()

Was ist die move_uploaded_file()-Funktion?

Die Funktion move_uploaded_file() ist eine eingebaute PHP-Funktion, die eine über ein HTML-Formular hochgeladene Datei an einen dauerhaften Speicherort auf dem Server verschiebt. Wenn ein Browser eine Datei hochlädt, speichert PHP sie zunächst in einem temporären Verzeichnis unter einem zufälligen Namen. Diese temporäre Datei wird automatisch gelöscht, wenn das Skript beendet wird. Daher müssen Sie sie an einen dauerhaften Ort verschieben, wenn Sie sie behalten möchten — genau dafür ist move_uploaded_file() gedacht.

Was diese Funktion besonders macht, ist ihre eingebaute Sicherheitsprüfung. Sie verschiebt eine Datei nur, wenn PHP bestätigt, dass die Datei tatsächlich über eine HTTP-POST-Anfrage hochgeladen wurde. Dies verhindert, dass ein Angreifer Ihr Skript dazu bringt, eine sensible Serverdatei (wie /etc/passwd) zu verschieben, indem er deren Pfad angibt. Aus diesem Grund sollten Sie für die Verarbeitung von Uploads immer move_uploaded_file() anstelle von copy() oder rename() verwenden.

Diese Seite behandelt die Syntax, Parameter, den Rückgabewert, ein vollständiges Arbeitsbeispiel, die Upload-Fehlercodes, die Sie prüfen sollten, sowie die Sicherheitsfallen, auf die Sie achten müssen.

Syntax

move_uploaded_file(string $from, string $to): bool

Rückgabewert

move_uploaded_file() gibt true zurück, wenn die Datei erfolgreich verschoben wurde. Es gibt false zurück, wenn $from keine gültige hochgeladene Datei ist (zum Beispiel wenn der Pfad gefälscht war) oder wenn das Verschieben selbst fehlschlägt — typischerweise wegen eines fehlenden Zielverzeichnisses oder unzureichender Schreibrechte. Im Fall einer gefälschten Datei gibt PHP außerdem eine Warnung aus, und es wird kein Verschieben durchgeführt.

Wie verwendet man die move_uploaded_file()-Funktion?

Die Verwendung der Funktion move_uploaded_file() ist unkompliziert. Hier sind die Schritte, die Sie befolgen sollten:

1. Überprüfen Sie, ob der Datei-Upload erfolgreich war, indem Sie $_FILES['file']['error'] prüfen.
2. Geben Sie den Zielpfad für die Datei an.
3. Rufen Sie die Funktion move_uploaded_file() auf und übergeben Sie den temporären Dateinamen und den Zielpfad.

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

Wie verwendet man die move_uploaded_file()-Funktion?

<?php

if ($_FILES['file']['error'] === UPLOAD_ERR_OK) {
    $uploaded_file = $_FILES['file']['tmp_name'];
    $destination_path = '/path/to/new/location/' . basename($_FILES['file']['name']);
    if (move_uploaded_file($uploaded_file, $destination_path)) {
        echo "File uploaded successfully!";
    } else {
        echo "Error uploading file.";
    }
} else {
    echo "File upload failed.";
}

In diesem Beispiel überprüfen wir zunächst, ob der Upload erfolgreich war, indem wir $_FILES['file']['error'] prüfen. Anschließend geben wir den Zielpfad für die Datei an und verwenden basename(), um den Dateinamen sicher zu extrahieren und Path-Traversal-Schwachstellen wie ../../config.php zu vermeiden. Schließlich verwenden wir die Funktion move_uploaded_file(), um die hochgeladene Datei an den neuen Speicherort zu verschieben. Wenn die Datei erfolgreich verschoben wird, geben wir eine Erfolgsmeldung aus. Wenn beim Verschieben ein Fehler auftritt, geben wir eine Fehlermeldung aus.

Das dazugehörige HTML-Formular muss method="post" und enctype="multipart/form-data" verwenden, sonst ist $_FILES leer:

<form action="upload.php" method="post" enctype="multipart/form-data">
    <input type="file" name="file">
    <input type="submit" value="Upload">
</form>

Das name-Attribut des Datei-Inputs (file hier) ist der Schlüssel, den Sie aus $_FILES auslesen.

Upload-Fehlercodes

Der Wert von $_FILES['file']['error'] gibt an, ob und warum ein Upload fehlgeschlagen ist. Prüfen Sie ihn immer, bevor Sie die Datei verschieben. Die häufigsten Codes sind:

Zwei Servereinstellungen verursachen häufig stille Fehler: upload_max_filesize und post_max_size. Wenn die hochgeladene Datei größer als eines der beiden Limits ist, kann $_FILES leer ankommen oder einen Fehlercode enthalten, egal wie korrekt Ihr PHP-Code ist.

Sicherheitshinweise

• Vertrauen Sie niemals dem ursprünglichen Dateinamen. Verwenden Sie basename() auf $_FILES['file']['name'] oder generieren Sie besser einen eigenen sicheren Namen, um Path-Traversal wie ../../config.php zu vermeiden.
• Validieren Sie den Dateityp anhand seines tatsächlichen Inhalts (zum Beispiel mit finfo / mime_content_type), nicht nur anhand seiner Erweiterung — der Client kann sowohl über die Erweiterung als auch über das type-Feld lügen.
• Speichern Sie Uploads nach Möglichkeit außerhalb des Web-Roots, damit Benutzer hochgeladene Skripte nicht direkt ausführen können.
• Für eine explizite Doppelprüfung, ob ein Pfad eine echte hochgeladene Datei ist, siehe is_uploaded_file() — obwohl move_uploaded_file() diese Überprüfung bereits intern durchführt.

Fazit

Die Funktion move_uploaded_file() ist der korrekte und sichere Weg, um eine über HTTP POST hochgeladene Datei aus dem temporären PHP-Verzeichnis an einen dauerhaften Speicherort zu verschieben. Sie gibt true bei Erfolg und false bei Misserfolg zurück und weigert sich, irgendetwas zu verschieben, das nicht tatsächlich hochgeladen wurde. Prüfen Sie immer zuerst den Upload-Fehlercode, bereinigen Sie den Zieldateinamen und validieren Sie die Datei, bevor Sie ihr vertrauen.

Für den umfassenderen Arbeitsablauf rund um die Verarbeitung von Uploads siehe PHP File Upload und den Rest von PHP File Handling.

Übungen