Signatur
Beschreibung
CURLFile ist die moderne, sichere Methode, um Dateien über eine cURL-POST-Anfrage hochzuladen. Vor PHP 5.5 wurde dazu der @-Präfix vor dem Dateipfad verwendet, was jedoch seit PHP 5.6 als veraltet gilt und in neueren Versionen nicht mehr unterstützt wird. Mit CURLFile werden Dateiname, MIME-Typ und ein optionaler Dateiname für die Übertragung klar und explizit angegeben.
Ein CURLFile-Objekt wird in einem Array übergeben, das als Wert von CURLOPT_POSTFIELDS gesetzt wird. Es wird dann als multipart/form-data-Upload gesendet, was dem HTML-Datei-Upload-Formular entspricht.
Folgende öffentliche Eigenschaften stehen zur Verfügung: name (Pfad zur Datei), mime (MIME-Typ der Datei) und postname (Dateiname im POST-Upload). Diese können auch über die bereitgestellten Getter- und Setter-Methoden gelesen und gesetzt werden.
Für das Hochladen von Dateiinhalten, die bereits als String vorliegen (ohne eine tatsächliche Datei auf der Festplatte), steht seit PHP 8.1 die Klasse CURLStringFile zur Verfügung.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $filename Pflicht | string | Pfad zur Datei, die hochgeladen werden soll. Muss ein gültiger, lesbarer Dateipfad auf dem Server sein. | |
| $mime_type | string | MIME-Typ der Datei, z. B. image/jpeg oder application/pdf. Wird dieser Wert weggelassen, versucht cURL, den MIME-Typ automatisch zu ermitteln. |
|
| $posted_filename | string | Dateiname, der im POST-Request an den Server übermittelt wird. Wenn nicht angegeben, wird der Basis-Dateiname aus filename verwendet. |
Beispiele
Bild per cURL-POST hochladen
<?php
$ch = curl_init('https://example.com/upload.php');
$cfile = new CURLFile('/var/www/uploads/foto.jpg', 'image/jpeg', 'mein-foto.jpg');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
'benutzername' => 'max',
'datei' => $cfile,
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$antwort = curl_exec($ch);
if (curl_errno($ch)) {
echo 'cURL-Fehler: ' . curl_error($ch);
} else {
echo 'Server-Antwort: ' . $antwort;
}
curl_close($ch);Mehrere Dateien gleichzeitig hochladen
<?php
$ch = curl_init('https://example.com/multi-upload.php');
$datei1 = new CURLFile('/pfad/zur/dokument.pdf', 'application/pdf', 'dokument.pdf');
$datei2 = new CURLFile('/pfad/zum/bild.png', 'image/png', 'bild.png');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
'titel' => 'Mehrfach-Upload-Test',
'datei1' => $datei1,
'datei2' => $datei2,
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$antwort = curl_exec($ch);
echo $antwort;
curl_close($ch);Getter- und Setter-Methoden von CURLFile nutzen
<?php
$cfile = new CURLFile('/var/www/daten/bericht.pdf');
// MIME-Typ nachträglich setzen
$cfile->setMimeType('application/pdf');
// Anzeigenamen für den Upload setzen
$cfile->setPostFilename('quartalsbericht-2024.pdf');
echo 'Dateipfad: ' . $cfile->getFilename() . PHP_EOL;
echo 'MIME-Typ: ' . $cfile->getMimeType() . PHP_EOL;
echo 'POST-Name: ' . $cfile->getPostFilename() . PHP_EOL;// Wichtig · Fallstricke
Sicherheitshinweis: Stellen Sie sicher, dass der Dateipfad, der an CURLFile übergeben wird, nicht aus nicht validierten Benutzereingaben stammt. Andernfalls könnte ein Angreifer beliebige Dateien vom Server hochladen (z. B. /etc/passwd). Validieren Sie Pfade stets mit realpath() und prüfen Sie, ob die Datei innerhalb eines erlaubten Verzeichnisses liegt.
Veralteter @-Präfix: Der alte Stil 'datei' => '@/pfad/zur/datei.jpg' ist seit PHP 5.6 veraltet und wurde in PHP 7.0 entfernt. Verwenden Sie ausschließlich CURLFile.
String-basierter Upload: Wenn Sie Dateiinhalte als String (ohne eine physische Datei) hochladen möchten, nutzen Sie stattdessen CURLStringFile (verfügbar ab PHP 8.1).