PHP http_response_code() Funktion

Jede HTTP-Antwort, die ein Server sendet, enthält einen Statuscode – eine dreistellige Zahl, die dem Browser (oder API-Client) mitteilt, ob die Anfrage erfolgreich war, umgeleitet wurde oder fehlgeschlagen ist. PHPs eingebaute Funktion http_response_code(), die ab PHP 5.4 verfügbar ist, ermöglicht das Lesen oder Setzen dieses Codes mit einem einzigen Aufruf. Es ist der einfachste und portabelste Weg, um aus einem PHP-Skript heraus ein 404 Not Found, eine 301-Weiterleitung, ein 403 Forbidden oder einen anderen Status zurückzugeben.

Dieses Kapitel behandelt die Syntax, den Unterschied zwischen Lesen und Setzen des aktuellen Codes, die häufigsten verwendeten Codes, die Fallstricke durch Output-Buffering sowie den Vergleich von http_response_code() mit dem manuellen Setzen der Statuszeile über header().

Was http_response_code() macht

http_response_code() hat zwei Modi, abhängig davon, ob ein Argument übergeben wird:

• Set-Modus — http_response_code(404) setzt den Antwort-Statuscode auf 404.
• Get-Modus — http_response_code() (ohne Argument) gibt den aktuellen Statuscode als Integer zurück, oder false (in der CLI gibt es true/false zurück), wenn im Web-Kontext noch kein Code gesetzt wurde.

Die Funktion berührt nur den Statuscode selbst. Sie sendet keinen Body, leitet den Browser nicht weiter und gibt keine Fehlerseite aus – das bleibt Ihre Aufgabe.

Syntax

http_response_code(int $response_code = null): int|bool

Rückgabewert: Beim Setzen wird der vorherige Code zurückgegeben (oder 200, wenn keiner gesetzt war). Beim Abrufen im Web-Kontext wird der aktuelle Code zurückgegeben. Außerhalb eines Webservers (CLI) gibt die Funktion nach dem Setzen true zurück und beim Lesen ohne gesetzten Code false.

Einen Statuscode setzen

Die klassische Verwendung ist die Rückgabe einer „Nicht gefunden"-Antwort aus einem Router oder einem Handler für fehlende Seiten:

<?php
// Tell the client this page does not exist
http_response_code(404);
echo "Page not found.";

Der 404 wird in den Response-Header geschrieben, der vor dem Body gesendet wird, sodass der Browser weiß, dass die Anfrage fehlgeschlagen ist, obwohl noch eine Nachricht ausgegeben wurde.

Ein 403 für eine gesperrte Ressource sieht genauso aus:

<?php
if (!$userIsLoggedIn) {
    http_response_code(403);
    exit("Access denied.");
}

Den aktuellen Statuscode lesen

Rufen Sie die Funktion ohne Argument auf, um herauszufinden, welchen Code die Antwort aktuell trägt – nützlich in Shutdown-Funktionen, beim Logging oder in Middleware:

<?php
http_response_code(404);

// Later in the same request:
$current = http_response_code();
echo $current; // 404

Weiterleitung mit einem Statuscode

Eine Weiterleitung erfordert zwei Dinge: den richtigen Statuscode und einen Location-Header. Verwenden Sie http_response_code() für den Code und header() für das Ziel:

<?php
// Permanent redirect to the new URL
http_response_code(301);
header("Location: https://www.w3docs.com/new-page");
exit;

Verwenden Sie 301 für eine dauerhafte Verschiebung (Suchmaschinen aktualisieren ihren Index) und 302/307 für eine vorübergehende.

Häufige HTTP-Statuscodes

Der „headers already sent"-Fallstrick

Statuscodes befinden sich in HTTP-Headern, und Header müssen vor jeder Ausgabe gesendet werden. Wenn Ihr Skript bereits HTML ausgegeben hat, eine Leerzeile ausgegeben hat oder sogar Leerzeichen vor dem öffnenden <?php-Tag vorhanden sind, sind die Header bereits gesendet worden und http_response_code() hat stillschweigend keine Wirkung (PHP gibt auch eine „headers already sent"-Warnung aus).

<?php
echo "Hello";          // body sent → headers are now locked
http_response_code(404); // too late, has no effect

Um zu prüfen, ob die Ausgabe bereits erfolgt ist, verwenden Sie headers_sent():

<?php
if (!headers_sent()) {
    http_response_code(404);
}

Lösungen für die häufigsten Ursachen: Leerzeichen vor <?php entfernen, echo/print vor dem Setzen des Codes vermeiden oder Output-Buffering mit ob_start() aktivieren, damit die Ausgabe zurückgehalten wird, bis Sie bereit sind.

http_response_code() vs. header()

Vor PHP 5.4 musste die Statuszeile manuell mit header() erstellt werden:

<?php
// The old way — still works, but verbose and you must repeat the protocol/text
header("HTTP/1.1 404 Not Found");

// The modern equivalent
http_response_code(404);

http_response_code() wird bevorzugt, weil Sie weder die HTTP-Version noch den Statustext hart kodieren müssen und die Funktion außerdem den aktuellen Code lesen kann – etwas, das ein reiner header()-Aufruf nicht kann. Für eine feinere Kontrolle über Response-Header siehe header() und headers_list().

Fazit

http_response_code() ist der sauberste Weg, einen HTTP-Statuscode in PHP zu lesen oder zu setzen. Denken Sie an die drei wichtigsten Dinge in der Praxis: rufen Sie die Funktion vor jeder Ausgabe auf, wählen Sie den richtigen Code für die Situation (404 für nicht vorhanden, 403 für verboten, 301/302 für Weiterleitungen) und kombinieren Sie Weiterleitungen mit einem Location-header(). Um tiefer in PHPs Anfrage-/Antwort-Werkzeuge einzutauchen, erkunden Sie PHP-Funktionen und die header()-Funktion.

Übungen