curl_setopt — Funktion · PHP-Referenz

Signatur

curl_setopt(CurlHandle $handle, int $option, mixed $value): bool

Beschreibung

curl_setopt() konfiguriert einen einzelnen Parameter eines cURL-Handles, das zuvor mit curl_init() erstellt wurde. Über den Parameter $option wird eine der vielen CURLOPT_*-Konstanten übergeben, die das Verhalten des Transfers steuern – von der Ziel-URL über Authentifizierungsdaten bis hin zu SSL-Einstellungen und Timeouts.

Die Funktion muss für jede Option einzeln aufgerufen werden. Sollen mehrere Optionen auf einmal gesetzt werden, ist curl_setopt_array() die kompaktere Alternative. Beide Funktionen überschreiben bereits gesetzte Werte für denselben $option-Schlüssel.

Typische Anwendungsfälle sind HTTP-GET- und POST-Anfragen, das Senden von JSON-Payloads, das Hochladen von Dateien, das Umgehen von SSL-Prüfungen in Entwicklungsumgebungen (niemals produktiv!) sowie das Folgen von Weiterleitungen mittels CURLOPT_FOLLOWLOCATION.

Die Rückgabe false zeigt an, dass die Option nicht gesetzt werden konnte – etwa weil der Handle ungültig ist oder die Kombination aus Option und Wert unzulässig ist. Im Erfolgsfall wird true zurückgegeben.

Parameter

Name	Typ	Beschreibung
$handle Pflicht	CurlHandle	Ein gültiges cURL-Handle-Objekt, das mit `curl_init()` erstellt wurde. Ab PHP 8.0 ist dies ein `CurlHandle`-Objekt; zuvor war es eine Resource.
$option Pflicht	int	Eine der `CURLOPT_*`-Konstanten, die festlegt, welche Einstellung geändert werden soll. Beispiele: `CURLOPT_URL`, `CURLOPT_RETURNTRANSFER`, `CURLOPT_POST`, `CURLOPT_HTTPHEADER`, `CURLOPT_TIMEOUT`.
$value Pflicht	mixed	Der Wert, der der Option zugewiesen wird. Der Typ hängt von der gewählten Option ab: Strings für URLs oder Header-Werte, boolesche Werte für Schalter wie `CURLOPT_RETURNTRANSFER`, Integer für numerische Werte wie `CURLOPT_TIMEOUT` oder Arrays für Header (`CURLOPT_HTTPHEADER`).

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn die Option erfolgreich gesetzt wurde, andernfalls false. Ein Fehler tritt auf, wenn der Handle ungültig ist, die Option unbekannt ist oder der Wert nicht zum erwarteten Typ der Option passt.

Beispiele

Einfacher HTTP-GET-Request mit Rückgabe der Antwort

<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://httpbin.org/get');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Antwort als String zurückgeben, nicht ausgeben
curl_setopt($ch, CURLOPT_TIMEOUT, 10);           // Maximale Laufzeit: 10 Sekunden

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'cURL-Fehler: ' . curl_error($ch);
} else {
    $data = json_decode($response, true);
    echo 'Ursprungs-IP: ' . $data['origin'];
}

curl_close($ch);

Ursprungs-IP: 93.184.216.34

HTTP-POST-Request mit JSON-Payload und eigenem Header

<?php
$payload = json_encode([
    'name'  => 'Max Mustermann',
    'email' => 'max@example.com',
]);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://httpbin.org/post');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Accept: application/json',
    'Content-Length: ' . strlen($payload),
]);
curl_setopt($ch, CURLOPT_TIMEOUT, 15);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if (curl_errno($ch)) {
    echo 'cURL-Fehler: ' . curl_error($ch);
} else {
    echo 'HTTP-Status: ' . $httpCode . PHP_EOL;
    $result = json_decode($response, true);
    echo 'Gesendete Daten: ' . $result['data'];
}

curl_close($ch);

HTTP-Status: 200 Gesendete Daten: {"name":"Max Mustermann","email":"max@example.com"}

Weiterleitungen folgen und Verbindungs-Timeout setzen

<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'http://httpbin.org/redirect/3'); // 3 Weiterleitungen
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);   // Weiterleitungen automatisch folgen
curl_setopt($ch, CURLOPT_MAXREDIRS, 5);            // Maximal 5 Weiterleitungen
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);       // Verbindungsaufbau max. 5 Sekunden
curl_setopt($ch, CURLOPT_TIMEOUT, 20);

$response = curl_exec($ch);
echo 'Finale URL: ' . curl_getinfo($ch, CURLINFO_EFFECTIVE_URL) . PHP_EOL;

curl_close($ch);

Finale URL: https://httpbin.org/get

// Wichtig · Fallstricke

Sicherheitshinweise:

SSL-Prüfung niemals in Produktion deaktivieren: CURLOPT_SSL_VERIFYPEER = false und CURLOPT_SSL_VERIFYHOST = 0 machen die Verbindung anfällig für Man-in-the-Middle-Angriffe. Diese Optionen sind ausschließlich für lokale Entwicklungsumgebungen gedacht.
URL-Validierung: Wenn die URL dynamisch aus Benutzereingaben stammt, muss sie vor der Übergabe an CURLOPT_URL validiert werden (z. B. mit filter_var($url, FILTER_VALIDATE_URL)), um Server-Side Request Forgery (SSRF) zu verhindern.
Credentials nicht in URLs: Zugangsdaten sollten über CURLOPT_USERPWD übergeben werden, nicht als Bestandteil der URL, um das Risiko des Durchsickerns in Logs zu reduzieren.

Performance-Tipp: Für viele gleichzeitige Anfragen sollte curl_multi_init() zusammen mit curl_multi_setopt() verwendet werden, da dies Anfragen parallel abarbeitet.

Versionsinformation: Bis PHP 7.4 war der Handle eine Resource vom Typ curl. Ab PHP 8.0 ist es eine Instanz der Klasse CurlHandle. Der Rückgabetyp ist in beiden Fällen identisch.

Siehe auch

curl_init curl_setopt_array curl_exec curl_getinfo curl_errno curl_error curl_close curl_multi_init