curl_file_create — Funktion · PHP-Referenz

Signatur

curl_file_create(string $filename, string $mime_type = '', string $posted_filename = ''): CURLFile

Beschreibung

curl_file_create() ist eine Hilfsfunktion, die ein CURLFile-Objekt erzeugt und damit das veraltete @/pfad/zur/datei-Syntax für Datei-Uploads über cURL ersetzt. Sie gibt ein Objekt zurück, das den lokalen Dateipfad, den MIME-Typ und den im Formular verwendeten Dateinamen kapselt.

Die Funktion ist besonders wichtig, da die alte @-Syntax ab PHP 5.5 als veraltet gilt und seit PHP 7.0 standardmäßig nicht mehr funktioniert, wenn CURLOPT_SAFE_UPLOAD auf true gesetzt ist. Mit CURLFile-Objekten werden Dateipfade nicht mehr versehentlich als Upload-Pfad interpretiert, was früher zu Sicherheitslücken führen konnte.

Typischer Einsatz ist das Hochladen von Dateien in einem Multipart-Formular (POST-Request), etwa beim Senden von Bildern, Dokumenten oder anderen Binärdaten an eine REST-API oder ein Webformular. Der MIME-Typ und der gepostete Dateiname sind optional, helfen aber dem Empfänger bei der korrekten Verarbeitung.

curl_file_create() ist ein Alias für new CURLFile($filename, $mime_type, $posted_filename) und kann überall dort verwendet werden, wo ein CURLFile-Objekt erwartet wird.

Parameter

Name	Typ	Beschreibung
$filename Pflicht	string	Absoluter oder relativer Pfad zur lokalen Datei, die hochgeladen werden soll.
$mime_type	string	MIME-Typ der Datei, z. B. `'image/jpeg'` oder `'application/pdf'`. Wird leer gelassen, ermittelt cURL keinen Typ automatisch — der Server erhält dann ggf. keinen Content-Type-Header für die Datei.
$posted_filename	string	Dateiname, der dem Server im Multipart-Formular übermittelt wird. Nützlich, wenn der tatsächliche lokale Dateiname vom gewünschten Übertragungsnamen abweicht.

Rückgabewert

Typ

CURLFile

Beschreibung

Gibt ein CURLFile-Objekt zurück, das als Wert in einem cURL-POST-Array verwendet werden kann.

Beispiele

Einfacher Datei-Upload per cURL

<?php
$ch = curl_init('https://example.com/upload');

$cfile = curl_file_create(
    '/var/www/uploads/foto.jpg',
    'image/jpeg',
    'mein-foto.jpg'
);

$postData = [
    'name'  => 'Max Mustermann',
    'photo' => $cfile,
];

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

MIME-Typ automatisch ermitteln und Datei hochladen

<?php
$filePath = '/tmp/dokument.pdf';

// MIME-Typ dynamisch ermitteln
$mimeType = mime_content_type($filePath);

$cfile = curl_file_create($filePath, $mimeType, basename($filePath));

$ch = curl_init('https://api.example.com/v1/documents');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => ['file' => $cfile, 'category' => 'reports'],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer geheim123'],
]);

$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "HTTP-Status: $status\n";
echo $result;

// Wichtig · Fallstricke

Sicherheitshinweis: Die frühere Methode, Dateien mit dem @-Präfix in einem POST-Array zu referenzieren (z. B. 'file' => '@/pfad/zur/datei'), ist gefährlich: Wenn Benutzereingaben ungeprüft in POST-Felder einfließen, könnten Angreifer durch ein vorangestelltes @ beliebige lokale Dateien hochladen. CURLFile bzw. curl_file_create() löst dieses Problem, da Dateipfade explizit und getrennt von regulären Feldwerten angegeben werden.

Ab PHP 7.0 ist CURLOPT_SAFE_UPLOAD standardmäßig true, sodass die @-Syntax für Uploads ohnehin nicht mehr funktioniert. Bestehenden Code sollte man auf curl_file_create() umstellen.

Die Datei muss auf dem ausführenden Server lesbar sein. Prüfe vor dem Upload mit is_readable(), ob die Datei existiert und zugänglich ist, um aussagekräftige Fehlermeldungen zu erzeugen.

Siehe auch

CURLFile curl_init curl_setopt curl_exec mime_content_type