move_uploaded_file — Funktion · PHP-Referenz

Signatur

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

Beschreibung

move_uploaded_file() überprüft zunächst, ob die Datei $from tatsächlich über den HTTP-POST-Mechanismus hochgeladen wurde (d. h. sie muss im temporären Upload-Verzeichnis von PHP liegen und als legitimer Upload registriert sein). Nur wenn diese Prüfung erfolgreich ist, wird die Datei an den Zielpfad $to verschoben. Dadurch wird verhindert, dass Angreifer beliebige Dateien des Servers über diese Funktion verschieben können.

Im Unterschied zu rename() oder copy() ist move_uploaded_file() die empfohlene Methode für das Verarbeiten von Datei-Uploads, weil sie die Sicherheitsprüfung direkt integriert. Sollte der Zielpfad bereits existieren, wird er überschrieben.

Typische Anwendungsfälle sind Upload-Formulare für Bilder, Dokumente oder andere Nutzerdateien. Nach dem Verschieben ist die Datei dauerhaft am Zielort gespeichert und die temporäre Datei wird entfernt.

Wichtig: Das Zielverzeichnis muss für den PHP-Prozess schreibbar sein, und der Dateiname sowie der Pfad sollten immer serverseitig validiert und bereinigt werden, bevor sie verwendet werden.

Parameter

Name	Typ	Default	Beschreibung
$from Pflicht	string		Der Pfad zur temporären hochgeladenen Datei, typischerweise aus `$_FILES['datei']['tmp_name']`.
$to Pflicht	string		Der vollständige Zielpfad (inkl. Dateiname), an den die Datei verschoben werden soll. Das Zielverzeichnis muss existieren und beschreibbar sein.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn die Datei erfolgreich verschoben wurde. Gibt false zurück und erzeugt eine PHP-Warnung, wenn $from kein gültiger HTTP-Upload ist, das Zielverzeichnis nicht beschreibbar ist oder ein anderer Fehler auftritt.

Beispiele

Einfacher Datei-Upload mit Zielverzeichnis

<?php
if ($_SERVER['REQUEST_METHOD'] === 'POST' && isset($_FILES['dokument'])) {
    $tmpName  = $_FILES['dokument']['tmp_name'];
    $origName = basename($_FILES['dokument']['name']);

    // Nur erlaubte Dateiendungen akzeptieren
    $erlaubteTypen = ['pdf', 'docx', 'txt'];
    $endung = strtolower(pathinfo($origName, PATHINFO_EXTENSION));

    if (!in_array($endung, $erlaubteTypen, true)) {
        die('Ungültiger Dateityp.');
    }

    $zielPfad = '/var/www/uploads/' . $origName;

    if (move_uploaded_file($tmpName, $zielPfad)) {
        echo 'Datei erfolgreich hochgeladen: ' . htmlspecialchars($origName);
    } else {
        echo 'Fehler beim Verschieben der Datei.';
    }
}

Datei erfolgreich hochgeladen: bericht.pdf

Upload mit generiertem, sicheren Dateinamen

<?php
if ($_SERVER['REQUEST_METHOD'] === 'POST' && isset($_FILES['bild'])) {
    $tmpName  = $_FILES['bild']['tmp_name'];
    $mimeType = mime_content_type($tmpName);

    // Nur Bilder erlauben
    $erlaubteMimeTypes = ['image/jpeg' => 'jpg', 'image/png' => 'png', 'image/gif' => 'gif'];

    if (!array_key_exists($mimeType, $erlaubteMimeTypes)) {
        die('Nur Bilddateien sind erlaubt.');
    }

    // Sicheren, einzigartigen Dateinamen generieren
    $neuerName = bin2hex(random_bytes(16)) . '.' . $erlaubteMimeTypes[$mimeType];
    $zielPfad  = '/var/www/uploads/bilder/' . $neuerName;

    if (move_uploaded_file($tmpName, $zielPfad)) {
        echo 'Bild gespeichert unter: ' . $neuerName;
    } else {
        echo 'Upload fehlgeschlagen.';
    }
}

Bild gespeichert unter: 3f8a1c2b4d9e7f0a1b2c3d4e5f6a7b8c.jpg

// Wichtig · Fallstricke

Sicherheitshinweise:

Originaldateinamen niemals direkt verwenden: $_FILES['datei']['name'] wird vom Client gesendet und kann Pfad-Traversal-Angriffe (../../etc/passwd) enthalten. Immer basename() verwenden oder besser einen eigenen, serverseitig generierten Dateinamen nutzen.
MIME-Typ nicht blind vertrauen: $_FILES['datei']['type'] stammt ebenfalls vom Client und ist leicht fälschbar. Den MIME-Typ serverseitig mit mime_content_type() oder der finfo-Erweiterung prüfen.
Ausführung verhindern: Upload-Verzeichnisse sollten so konfiguriert sein, dass PHP-Dateien dort nicht ausgeführt werden können (z. B. via .htaccess oder Webserver-Konfiguration).
Dateigrößen begrenzen: Sowohl in der php.ini (upload_max_filesize, post_max_size) als auch durch eigene Validierung begrenzen.
Die Funktion gibt false zurück und gibt eine Warnung aus, wenn die Quelldatei kein gültiger HTTP-Upload ist – das ist die eingebaute Sicherheitsmaßnahme gegen Missbrauch.

Siehe auch

is_uploaded_file rename copy mime_content_type pathinfo basename