CURLStringFile — Klasse · PHP-Referenz

Signatur

class CURLStringFile

Beschreibung

CURLStringFile ist eine Klasse, die es erlaubt, Dateiinhalte in cURL-Multipart-POST-Anfragen einzubetten, ohne dass die Daten zuvor in eine temporäre Datei geschrieben werden müssen. Der Dateiinhalt wird direkt als PHP-String übergeben – ideal für dynamisch erzeugte Inhalte, Daten aus einer Datenbank oder Streams, die bereits im Speicher vorliegen.

Sie ist das funktionale Gegenstück zu CURLFile: Während CURLFile einen Dateipfad erwartet, nimmt CURLStringFile den rohen Dateiinhalt als String entgegen. Beide Klassen können als Wert in einem POST-Daten-Array gesetzt werden, das an CURLOPT_POSTFIELDS übergeben wird.

Typische Anwendungsfälle sind das Hochladen von generierten Bildern, PDF-Dokumenten oder anderen Binärdaten zu einer API, ohne temporäre Dateien anlegen zu müssen. Dies erhöht die Performance und vermeidet potenziell unsichere oder fehleranfällige Dateioperationen.

Der mime_type-Parameter sollte korrekt gesetzt werden, da viele APIs den MIME-Typ zur Validierung nutzen.
Der postname definiert den Dateinamen, der dem empfangenden Server mitgeteilt wird.

Parameter

Name	Typ	Default	Beschreibung
$data Pflicht	string		Der rohe Inhalt der hochzuladenden Datei als PHP-String (kann Binärdaten enthalten).
$postname Pflicht	string		Der Dateiname, der im Multipart-Upload-Header als `filename` angegeben wird. Er ist für den Empfänger sichtbar und sollte einen sinnvollen Namen wie z. B. `bild.png` enthalten.
$mime_type	string	application/octet-stream	Der MIME-Typ der hochzuladenden Datei, z. B. `image/png` oder `application/pdf`. Standardmäßig wird `application/octet-stream` verwendet.

Rückgabewert

Typ

void

Beispiele

PNG-Bild aus GD-Bibliothek direkt hochladen

<?php
// Bild dynamisch erzeugen (kein Dateisystem nötig)
$image = imagecreatetruecolor(100, 100);
$color = imagecolorallocate($image, 255, 0, 0);
imagefill($image, 0, 0, $color);

// PNG-Daten in einen String-Buffer schreiben
ob_start();
imagepng($image);
$imageData = ob_get_clean();
imagedestroy($image);

// CURLStringFile mit den Bilddaten erstellen
$curlFile = new CURLStringFile($imageData, 'bild.png', 'image/png');

$ch = curl_init('https://httpbin.org/post');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
    'datei' => $curlFile,
    'beschreibung' => 'Ein dynamisch erzeugtes Bild',
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

echo $response;

PDF-Inhalt aus Datenbank hochladen

<?php
// Simulierter PDF-Inhalt aus einer Datenbank
$pdo = new PDO('mysql:host=localhost;dbname=dokumente', 'user', 'pass');
$stmt = $pdo->prepare('SELECT inhalt, dateiname FROM dokumente WHERE id = ?');
$stmt->execute([42]);
$dokument = $stmt->fetch(PDO::FETCH_ASSOC);

if ($dokument) {
    $curlFile = new CURLStringFile(
        $dokument['inhalt'],
        $dokument['dateiname'],
        'application/pdf'
    );

    $ch = curl_init('https://api.beispiel.de/upload');
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, [
        'dokument' => $curlFile,
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer mein-api-token',
    ]);

    $antwort = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    echo "HTTP-Status: $httpCode\n";
    echo $antwort;
}

// Wichtig · Fallstricke

Sicherheit: Wenn der postname oder der MIME-Typ aus Benutzereingaben stammt, müssen diese unbedingt validiert und bereinigt werden. Ein manipulierter Dateiname kann auf dem Empfänger-Server zu Sicherheitsproblemen führen.

Speicherverbrauch: Da der gesamte Dateiinhalt als PHP-String im RAM liegt, sollte bei sehr großen Dateien abgewogen werden, ob CURLFile mit einem temporären Dateipfad nicht ressourcenschonender ist.

Eigenschaften: Die Klasse hat drei öffentliche Eigenschaften: $data (der Dateiinhalt), $name (der Dateiname / Postname) und $mime (der MIME-Typ), die nach der Instanziierung direkt gelesen und gesetzt werden können.

Kompatibilität: CURLStringFile steht erst ab PHP 8.1.0 zur Verfügung. Für ältere PHP-Versionen muss der Dateiinhalt zunächst in eine temporäre Datei geschrieben und dann über CURLFile referenziert werden.

Siehe auch

CURLFile curl_init curl_setopt curl_exec