PHP curl_getinfo(): HTTP-Statuscode und Transfer-Informationen abrufen

Bei HTTP-Anfragen mit cURL reicht es selten aus, nur die Antwort des Servers zu erhalten. Genauso wichtig sind Metadaten wie der HTTP-Statuscode, die Antwortzeit oder der Content-Type. Die PHP-Funktion curl_getinfo() liefert genau diese Informationen. Sie wird nach curl_exec() aufgerufen und gibt wahlweise alle Transfer-Daten als assoziatives Array oder einen einzelnen Wert über eine CURLINFO-Konstante zurück. In diesem Tutorial lernst du die wichtigsten Konstanten kennen, siehst praxisnahe Code-Beispiele und erfährst, wie curl_getinfo() mit curl_error() zusammenarbeitet.

Den Anfang macht ein Überblick über die Funktionsweise und die wichtigsten CURLINFO-Konstanten wie CURLINFO_HTTP_CODE und CURLINFO_TOTAL_TIME.

Was macht curl_getinfo()?

Die Funktion curl_getinfo() liest Informationen über einen abgeschlossenen oder laufenden cURL-Transfer aus. Sie erwartet als ersten Parameter ein cURL-Handle und akzeptiert optional eine CURLINFO-Konstante als zweiten Parameter. Ohne diesen zweiten Parameter gibt die Funktion ein assoziatives Array mit sämtlichen verfügbaren Transfer-Informationen zurück. Wird eine Konstante angegeben, liefert sie nur den entsprechenden Einzelwert.

<?php

$ch = curl_init('https://example.com');

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

curl_exec($ch);



/* Alle Informationen als Array */

$info = curl_getinfo($ch);



/* Einzelnen Wert abrufen */

$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);



curl_close($ch);

Wichtig ist dabei die Reihenfolge: curl_getinfo() muss immer nach curl_exec() aufgerufen werden. Vor der Ausführung des Requests enthält das Handle noch keine Transfer-Daten, und die meisten Werte wären leer oder null.

Die wichtigsten CURLINFO-Konstanten

PHP stellt eine Vielzahl von CURLINFO-Konstanten bereit, die jeweils einen bestimmten Aspekt des Transfers beschreiben. Die folgenden fünf Konstanten gehören zu den am häufigsten verwendeten.

CURLINFO_HTTP_CODE

Diese Konstante ist mit Abstand die meistgenutzte. Sie gibt den HTTP-Statuscode der Antwort als Integer zurück. Bei einer erfolgreichen Anfrage ist das typischerweise 200, bei einer Weiterleitung 301 oder 302, und bei einem Fehler 404 oder 500. Schlägt der Request komplett fehl, etwa weil der Server nicht erreichbar ist, gibt curl_getinfo() den Wert 0 zurück. Bei Redirects zeigt der Statuscode immer den letzten Request in der Weiterleitungskette an.

<?php

$ch = curl_init('https://example.com/api/users');

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

curl_exec($ch);



$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);



if ($httpCode === 200) {

 echo 'Anfrage erfolgreich';

} elseif ($httpCode === 0) {

 echo 'Verbindung fehlgeschlagen';

} else {

 echo 'HTTP-Fehler: ' . $httpCode;

}



curl_close($ch);

CURLINFO_TOTAL_TIME

Diese Konstante liefert die gesamte Dauer des Transfers in Sekunden als Float-Wert. Die Zeit umfasst DNS-Auflösung, Verbindungsaufbau, TLS-Handshake, Senden der Anfrage und Empfangen der Antwort. Sie eignet sich hervorragend, um die Performance externer API-Aufrufe zu überwachen. Neben CURLINFO_TOTAL_TIME gibt es verwandte Konstanten wie CURLINFO_NAMELOOKUP_TIME, CURLINFO_CONNECT_TIME und CURLINFO_STARTTRANSFER_TIME, die einzelne Phasen des Transfers separat messen.

CURLINFO_CONTENT_TYPE

Der Content-Type-Header der Antwort wird als String zurückgegeben, zum Beispiel application/json; charset=utf-8. Damit lässt sich prüfen, ob die Antwort im erwarteten Format vorliegt, bevor sie weiterverarbeitet wird. Wenn der Server keinen Content-Type-Header sendet, gibt die Funktion null zurück. In der Praxis empfiehlt es sich, den Wert vor der Weiterverarbeitung mit str_contains() auf den erwarteten MIME-Type zu prüfen.

CURLINFO_REDIRECT_COUNT

Bei aktivierter Option CURLOPT_FOLLOWLOCATION zählt diese Konstante die Anzahl der durchlaufenen Weiterleitungen. Sie gibt einen Integer zurück und hilft dabei, unnötige Redirect-Ketten zu erkennen. Ist CURLOPT_FOLLOWLOCATION nicht aktiviert, bleibt der Wert immer 0, da cURL in diesem Fall Weiterleitungen nicht automatisch verfolgt.

CURLINFO_EFFECTIVE_URL

Diese Konstante gibt die URL zurück, die tatsächlich aufgerufen wurde. Bei Weiterleitungen unterscheidet sie sich von der ursprünglich angegebenen URL. So lässt sich nachvollziehen, wohin ein Redirect letztlich geführt hat.

Alle Transfer-Informationen als Array abrufen

Wird curl_getinfo() ohne zweiten Parameter aufgerufen, gibt die Funktion ein umfangreiches assoziatives Array mit allen verfügbaren Werten zurück. Dieses Array enthält unter anderem Schlüssel wie http_code, total_time, content_type, redirect_count, primary_ip und viele weitere.

<?php

$ch = curl_init('https://example.com');

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);

curl_exec($ch);



$info = curl_getinfo($ch);



echo 'HTTP-Code: ' . $info['http_code'];

echo 'Gesamtzeit: ' . $info['total_time'] . ' Sekunden';

echo 'Content-Type: ' . $info['content_type'];

echo 'Redirects: ' . $info['redirect_count'];

echo 'Finale URL: ' . $info['url'];

echo 'Primaere IP: ' . $info['primary_ip'];



curl_close($ch);

Das vollständige Array eignet sich besonders für Debugging-Zwecke. Während der Entwicklung kann es mit print_r() oder var_dump() ausgegeben werden, um alle verfügbaren Metriken auf einen Blick zu sehen. In Produktionsumgebungen lassen sich ausgewählte Werte aus dem Array in eine Logdatei schreiben, um die Performance und Zuverlässigkeit externer Dienste langfristig zu dokumentieren.

Praxisbeispiel: HTTP-Statuscode prüfen

In der Praxis wird curl_getinfo() am häufigsten eingesetzt, um den HTTP-Statuscode einer API-Antwort auszuwerten. Das folgende Beispiel zeigt eine robuste Funktion, die einen GET-Request durchführt und anhand des Statuscodes entscheidet, wie die Antwort verarbeitet wird.

<?php

function apiRequest(string $url): array

{

 $ch = curl_init($url);

 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

 curl_setopt($ch, CURLOPT_TIMEOUT, 10);

 curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);



 $response = curl_exec($ch);

 $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

 $contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE);

 curl_close($ch);



 if ($httpCode >= 200 && $httpCode < 300) {

 return [

 'erfolg' => true,

 'daten' => json_decode($response, true),

 'code' => $httpCode

 ];

 }



 return [

 'erfolg' => false,

 'fehler' => 'HTTP-Fehler ' . $httpCode,

 'code' => $httpCode,

 'antwort' => $response

 ];

}



$ergebnis = apiRequest('https://api.example.com/produkte');



if ($ergebnis['erfolg']) {

 echo 'Produkte geladen: ' . count($ergebnis['daten']);

} else {

 echo $ergebnis['fehler'];

}

Der Statuscode 0 verdient besondere Aufmerksamkeit. Er tritt auf, wenn der Request erst gar nicht abgeschlossen werden konnte, etwa bei einem DNS-Fehler, einem Timeout oder einer abgelehnten Verbindung. In diesem Fall sollte zusätzlich curl_error() abgefragt werden, um die genaue Fehlerursache zu ermitteln.

Praxisbeispiel: Antwortzeit messen

Die Konstante CURLINFO_TOTAL_TIME ermöglicht es, die Antwortzeit externer Services gezielt zu überwachen. Das folgende Beispiel prüft mehrere Endpunkte und protokolliert langsame Antworten.

<?php

$endpunkte = [

 'https://api.example.com/status',

 'https://api.example.com/produkte',

 'https://api.example.com/benutzer'

];



$schwellwert = 2.0; /* Sekunden */



foreach ($endpunkte as $url) {

 $ch = curl_init($url);

 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

 curl_setopt($ch, CURLOPT_TIMEOUT, 10);

 curl_exec($ch);



 $zeit = curl_getinfo($ch, CURLINFO_TOTAL_TIME);

 $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

 curl_close($ch);



 $status = ($zeit > $schwellwert) ? 'LANGSAM' : 'OK';

 echo $status . ' | ' . $url . ' | ' . round($zeit, 3) . 's | HTTP ' . $code;

}

Solche Messungen lassen sich in Cronjobs einbauen, um die Verfügbarkeit und Geschwindigkeit externer APIs dauerhaft zu überwachen. Bei Überschreitung des Schwellwerts könnte zusätzlich eine Benachrichtigung per E-Mail oder in ein Monitoring-System gesendet werden.

curl_getinfo() im Zusammenspiel mit curl_error()

Die Funktion curl_getinfo() liefert nur dann aussagekräftige Werte, wenn der Transfer zumindest teilweise stattgefunden hat. Schlägt der Request auf Netzwerkebene fehl, ist der HTTP-Code 0 und die meisten Zeitwerte sind leer. In solchen Fällen liefert curl_error() die eigentliche Fehlerbeschreibung, während curl_errno() den numerischen Fehlercode zurückgibt.

flowchart TD
    A[curl_exec] --> B{Ergebnis false?}
    B -- Ja --> C[curl_error aufrufen]
    C --> D[Netzwerkfehler behandeln]
    B -- Nein --> E[curl_getinfo aufrufen]
    E --> F{http_code pruefen}
    F -- 2xx --> G[Erfolg: Antwort verarbeiten]
    F -- 4xx/5xx --> H[HTTP-Fehler behandeln]
    F -- 0 --> C

Das folgende Beispiel kombiniert beide Funktionen zu einer vollständigen Fehlerbehandlung:

<?php

$ch = curl_init('https://api.example.com/daten');

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

curl_setopt($ch, CURLOPT_TIMEOUT, 5);



$response = curl_exec($ch);



if ($response === false) {

 $fehlerNr = curl_errno($ch);

 $fehlerText = curl_error($ch);

 echo 'cURL-Fehler #' . $fehlerNr . ': ' . $fehlerText;

} else {

 $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

 $totalTime = curl_getinfo($ch, CURLINFO_TOTAL_TIME);



 if ($httpCode >= 200 && $httpCode < 300) {

 echo 'Erfolgreich in ' . round($totalTime, 3) . ' Sekunden';

 } else {

 echo 'Server antwortete mit HTTP ' . $httpCode;

 }

}



curl_close($ch);

Diese Kombination deckt beide Fehlerarten ab: Netzwerkfehler, bei denen gar keine HTTP-Antwort eintrifft, und HTTP-Fehler, bei denen der Server zwar antwortet, aber mit einem Fehlerstatuscode. Als Best Practice empfiehlt es sich, diese Prüfungen in eine wiederverwendbare Funktion auszulagern, die in allen cURL-Aufrufen des Projekts eingesetzt wird. So entsteht eine einheitliche Fehlerbehandlung, die später leicht um Logging oder Retry-Logik erweitert werden kann.

Übersicht der wichtigsten CURLINFO-Konstanten

Die folgende Tabelle fasst die gebräuchlichsten Konstanten zusammen und zeigt den jeweiligen Rückgabetyp sowie den zugehörigen Array-Schlüssel.

Die Schlüsselnamen im Array stimmen nicht immer mit dem Konstantennamen überein. So heißt der Schlüssel für CURLINFO_EFFECTIVE_URL im Array schlicht url, nicht effective_url. Bei der Arbeit mit dem vollständigen Array sollte daher ein Blick in die offizielle PHP-Dokumentation geworfen werden.

Fazit

Die Funktion curl_getinfo() ist ein unverzichtbares Werkzeug für jeden, der in PHP mit cURL arbeitet. Sie liefert nach dem Aufruf von curl_exec() detaillierte Informationen über den abgeschlossenen Transfer. Am häufigsten wird CURLINFO_HTTP_CODE verwendet, um den Statuscode der Antwort zu prüfen. Mit CURLINFO_TOTAL_TIME lassen sich Antwortzeiten messen und langsame Endpunkte identifizieren. Ohne zweiten Parameter gibt die Funktion ein umfangreiches Array mit allen verfügbaren Metriken zurück, was besonders beim Debugging hilfreich ist. In Kombination mit curl_error() entsteht eine robuste Fehlerbehandlung, die sowohl Netzwerkfehler als auch HTTP-Fehlercodes zuverlässig abfängt.