curl_setopt_array — Funktion · PHP-Referenz

Signatur

curl_setopt_array(CurlHandle $handle, array $options): bool

Beschreibung

curl_setopt_array ist die effiziente Alternative zu mehreren aufeinanderfolgenden curl_setopt-Aufrufen. Statt jede Option einzeln zu setzen, übergibt man ein assoziatives Array, bei dem die Schlüssel die CURLOPT_*-Konstanten sind und die Werte die gewünschten Einstellungen.

Die Funktion gibt false zurück, sobald eine Option ungültig ist – bereits gesetzte Optionen werden dabei jedoch nicht zurückgesetzt. Es empfiehlt sich daher, den Rückgabewert zu prüfen und bei Bedarf auf Fehler zu reagieren.

Typische Einsatzgebiete sind HTTP-GET- und POST-Anfragen, das Setzen von Headern, Timeouts, SSL-Verhalten und Authentifizierungsdaten. Durch das Array-Format lässt sich die Konfiguration gut auslagern, zusammenführen oder dynamisch aufbauen, was den Code lesbarer und wartbarer macht.

Seit PHP 8.0 erwartet die Funktion ein CurlHandle-Objekt anstelle einer Resource.

Parameter

Name	Typ	Default	Beschreibung
$handle Pflicht	CurlHandle		Ein gültiges cURL-Handle, das zuvor mit `curl_init()` erstellt wurde.
$options Pflicht	array		Assoziatives Array mit `CURLOPT_*`-Konstanten als Schlüssel und den jeweiligen Optionswerten. Entspricht exakt den Parametern, die einzeln an `curl_setopt()` übergeben würden.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn alle Optionen erfolgreich gesetzt wurden. Gibt false zurück, sobald eine Option nicht gesetzt werden konnte – bereits gesetzte Optionen aus dem Array bleiben jedoch aktiv.

Beispiele

Einfache GET-Anfrage mit mehreren Optionen

<?php
$ch = curl_init();

$success = curl_setopt_array($ch, [
    CURLOPT_URL            => 'https://api.example.com/data',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_USERAGENT      => 'MeinPHP-Client/1.0',
]);

if (!$success) {
    die('Fehler beim Setzen der cURL-Optionen: ' . curl_error($ch));
}

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'cURL-Fehler: ' . curl_error($ch);
} else {
    echo $response;
}

curl_close($ch);

// Gibt den Body der API-Antwort aus

POST-Anfrage mit JSON-Body und Authentifizierungsheader

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

$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL            => 'https://api.example.com/users',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'Authorization: Bearer mein-geheimes-token',
        'Content-Length: ' . strlen($payload),
    ],
    CURLOPT_TIMEOUT        => 15,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_SSL_VERIFYHOST => 2,
]);

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

if (curl_errno($ch)) {
    echo 'Fehler: ' . curl_error($ch);
} else {
    echo 'HTTP-Status: ' . $httpCode . PHP_EOL;
    echo 'Antwort: ' . $response;
}

curl_close($ch);

// HTTP-Status: 201 // Antwort: {"id": 42, "name": "Max", ...}

Optionen dynamisch zusammenführen (Basis + spezifisch)

<?php
$defaultOptions = [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_USERAGENT      => 'MeinApp/2.0',
];

$requestOptions = [
    CURLOPT_URL  => 'https://api.example.com/status',
    CURLOPT_POST => false,
];

// Spezifische Optionen überschreiben Standardwerte
$mergedOptions = $requestOptions + $defaultOptions;

$ch = curl_init();
curl_setopt_array($ch, $mergedOptions);

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

echo $response;

// Gibt den Antwort-Body zurück

// Wichtig · Fallstricke

Sicherheitshinweise:

Setze CURLOPT_SSL_VERIFYPEER und CURLOPT_SSL_VERIFYHOST niemals auf false in Produktivumgebungen – damit deaktivierst du die SSL-Zertifikatsprüfung und öffnest Man-in-the-Middle-Angriffe.
Füge Benutzereingaben niemals ungeprüft in CURLOPT_URL ein, da dies zu SSRF-Angriffen (Server-Side Request Forgery) führen kann. Validiere URLs stets vor der Verwendung.
Tokens und Passwörter in Headern oder POST-Feldern sollten aus sicheren Konfigurationsquellen stammen und nicht hartcodiert sein.

Verhalten bei Fehlern: Wenn eine Option im Array ungültig ist, bricht curl_setopt_array ab und gibt false zurück. Alle vorher im Array verarbeiteten Optionen sind jedoch bereits aktiv. Eine Möglichkeit zur Fehlerdiagnose ist curl_error($ch).

PHP 8.0+: Das Handle ist nun ein CurlHandle-Objekt statt einer Resource. Bestehender Code, der auf Ressource-Typen prüft, muss angepasst werden.

Siehe auch

curl_setopt curl_init curl_exec curl_error curl_getinfo curl_close