</> programmierung.net
Start · Sprachen · PHP · Referenz · HTTP context options

HTTP context options

Funktion

HTTP-Kontextoptionen steuern das Verhalten von HTTP-Streams, die mit Wrapper-Funktionen wie <code>file_get_contents()</code> oder <code>fopen()</code> geöffnet werden.

seit PHP 5.0.0 Kategorie: misc

Signatur

stream_context_create(['http' => [...options]])

Beschreibung

HTTP-Kontextoptionen werden einem Stream-Kontext übergeben und beeinflussen, wie PHP HTTP-Anfragen über den http://- und https://-Wrapper abwickelt. Sie ermöglichen es, Methode, Header, Body, Redirects, Proxies, Timeouts und weitere Parameter einer HTTP-Anfrage zu konfigurieren, ohne eine externe Bibliothek wie cURL zu benötigen.

Ein Kontext wird mit stream_context_create() erzeugt und anschließend als letzter Parameter an Stream-Funktionen wie file_get_contents(), fopen() oder file() übergeben. Die Optionen werden unter dem Schlüssel 'http' als assoziatives Array angegeben – obwohl der Name nur http lautet, gilt dieser Kontext auch für HTTPS-Verbindungen.

Typische Anwendungsfälle sind: HTTP-POST-Anfragen mit Formulardaten, Hinzufügen von Authentifizierungs-Headern, Deaktivieren von SSL-Prüfungen in Entwicklungsumgebungen sowie das Setzen von Timeouts für externe API-Aufrufe. Für komplexere Szenarien (z. B. Cookies, Session-Management) ist cURL oft flexibler.

  • method: HTTP-Methode (GET, POST, PUT, DELETE, …)
  • header: Zusätzliche HTTP-Header als String oder Array
  • content: Der Anfrage-Body (z. B. POST-Daten)
  • user_agent: User-Agent-String; überschreibt user_agent aus der php.ini
  • proxy: URL eines HTTP-Proxys
  • follow_location: Redirects automatisch folgen (1 = ja, 0 = nein)
  • max_redirects: Maximale Anzahl von Redirects (Standard: 20)
  • timeout: Verbindungs-Timeout in Sekunden (float)
  • ignore_errors: Auch bei HTTP-Fehlercodes (4xx/5xx) den Body lesen
  • protocol_version: HTTP-Protokollversion (1.0 oder 1.1)

Parameter

Name Typ Default Beschreibung
$method string GET Die HTTP-Anfragemethode, z. B. 'GET', 'POST', 'PUT' oder 'DELETE'.
$header string|array Zusätzliche HTTP-Header, entweder als String (zeilengetrennt) oder als Array von Strings im Format 'Name: Wert'.
$user_agent string Der User-Agent-Header. Überschreibt die php.ini-Einstellung user_agent.
$content string Der Inhalt des Anfrage-Body, z. B. URL-kodierte POST-Daten oder JSON.
$proxy string URL eines HTTP-Proxy-Servers, z. B. 'tcp://proxy.example.com:8080'.
$request_fulluri bool false Wenn true, wird die vollständige URI in der Anfrage gesendet (für manche Proxy-Server erforderlich).
$follow_location int 1 Steuert, ob Weiterleitungen (HTTP 301/302/…) automatisch verfolgt werden. 0 deaktiviert das Folgen.
$max_redirects int 20 Maximale Anzahl von Weiterleitungen, die automatisch verfolgt werden.
$protocol_version float 1.1 HTTP-Protokollversion: 1.0 oder 1.1.
$timeout float ini_get('default_socket_timeout') Verbindungs-Timeout in Sekunden. Akzeptiert Dezimalwerte für Millisekunden-Genauigkeit.
$ignore_errors bool false Wenn true, wird der Response-Body auch bei HTTP-Fehlercodes (4xx, 5xx) zurückgegeben, anstatt einen Fehler auszulösen.

Rückgabewert

Typ
resource
Beschreibung
Der Stream-Kontext wird von stream_context_create() als Ressource zurückgegeben und an Stream-Funktionen übergeben.

Beispiele

Einfacher HTTP-GET-Request mit Timeout und eigenem Header

<?php
$context = stream_context_create([
    'http' => [
        'method'  => 'GET',
        'header'  => [
            'Accept: application/json',
            'Authorization: Bearer mein-api-token',
        ],
        'timeout' => 5.0,
    ],
]);

$response = file_get_contents('https://api.example.com/users', false, $context);

if ($response === false) {
    echo 'Anfrage fehlgeschlagen.';
} else {
    $data = json_decode($response, true);
    print_r($data);
}

HTTP-POST-Request mit JSON-Body

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

$context = stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => [
            'Content-Type: application/json',
            'Content-Length: ' . strlen($payload),
        ],
        'content' => $payload,
        'timeout' => 10.0,
        'ignore_errors' => true, // Auch bei 4xx/5xx Body lesen
    ],
]);

$response = file_get_contents('https://api.example.com/users', false, $context);

// HTTP-Statuscode aus den Response-Headern auslesen
$status = $http_response_header[0] ?? 'Unbekannt';
echo 'Status: ' . $status . PHP_EOL;
echo 'Antwort: ' . $response;
Status: HTTP/1.1 201 Created Antwort: {"id":42,"name":"Maria"}

Anfrage über einen HTTP-Proxy

<?php
$context = stream_context_create([
    'http' => [
        'method'           => 'GET',
        'proxy'            => 'tcp://proxy.intern.example.com:3128',
        'request_fulluri'  => true,
        'follow_location'  => 1,
        'max_redirects'    => 5,
    ],
]);

$html = file_get_contents('http://www.example.com/', false, $context);
echo mb_substr($html, 0, 200);

// Wichtig · Fallstricke

Sicherheitshinweis: Verwende niemals benutzerkontrollierte Eingaben ungeprüft als Header-Werte — HTTP-Header-Injection ist möglich. Validiere und sanitisiere alle dynamischen Werte.

SSL/TLS: Für HTTPS können zusätzlich SSL-Kontextoptionen unter dem Schlüssel 'ssl' gesetzt werden, z. B. 'verify_peer' => false. Das Deaktivieren der Zertifikatsprüfung ist jedoch nur in Entwicklungsumgebungen akzeptabel und in Produktion ein erhebliches Sicherheitsrisiko.

$http_response_header: Nach einem erfolgreichen Stream-Aufruf ist die globale Variable $http_response_header automatisch mit den HTTP-Antwort-Headern befüllt — nützlich zum Auslesen des Status-Codes.

Alternativen: Für komplexe Szenarien (Cookies, mehrere Anfragen, parallele Requests) ist die cURL-Erweiterung (curl_exec()) oder eine Bibliothek wie Guzzle besser geeignet.

Siehe auch

stream_context_create file_get_contents fopen stream_context_set_option $http_response_header SSL context options curl_exec
← Vorheriger Eintrag HRTime\Unit