request_parse_body — Funktion · PHP-Referenz

Signatur

request_parse_body(?array $options = null): array

Beschreibung

request_parse_body() wurde in PHP 8.4 eingeführt und ermöglicht es, den HTTP-Request-Body explizit zu lesen und zu parsen – unabhängig davon, ob PHP dies bereits automatisch in $_POST und $_FILES vorgenommen hat. Die Funktion ist besonders nützlich für CLI-SAPI-Anwendungen, benutzerdefinierte Request-Handler oder Situationen, in denen der Body mehrfach oder mit abweichenden Optionen geparst werden soll.

Der Rückgabewert ist ein Array mit genau zwei Elementen: Das erste Element entspricht dem Inhalt von $_POST (geparste POST-Felder), das zweite dem Inhalt von $_FILES (hochgeladene Dateien). Dies erlaubt eine strukturierte Verarbeitung ähnlich wie bei Standard-PHP-Requests, ohne auf die Superglobalen angewiesen zu sein.

Über den optionalen Parameter $options lassen sich Grenzen und Verhaltensweisen beim Parsen steuern, etwa die maximale Anzahl an POST-Feldern oder die maximale Dateigröße. Damit können Anwendungen eigene, von den globalen php.ini-Einstellungen abweichende Limits durchsetzen.

Die Funktion ist ideal für moderne PHP-Anwendungen, die HTTP-Requests selbst verwalten – z. B. in Verbindung mit Frameworks, die Middleware-Konzepte verwenden –, oder für die Verarbeitung von Request-Bodies in Szenarien, in denen $_POST bewusst nicht befüllt werden soll.

Parameter

Name	Typ	Default	Beschreibung
$options	array\|null	null	Optionales assoziatives Array zur Konfiguration des Parse-Vorgangs. Unterstützte Schlüssel sind unter anderem: `post_max_vars` (maximale Anzahl POST-Variablen), `max_file_uploads` (maximale Anzahl Datei-Uploads) und weitere, an die entsprechenden `php.ini`-Direktiven angelehnte Einstellungen. Wird `null` übergeben, gelten die Standardwerte aus der `php.ini`.

Rückgabewert

Typ

array

Beschreibung

Gibt ein indiziertes Array mit genau zwei Elementen zurück: [0] enthält ein assoziatives Array mit den geparsten POST-Feldern (analog zu $_POST), [1] enthält ein assoziatives Array mit den hochgeladenen Dateien (analog zu $_FILES). Im Fehlerfall oder bei einem leeren Body werden entsprechend leere Arrays zurückgegeben.

Beispiele

Einfaches Parsen eines POST-Requests

<?php
// Simulierter Aufruf in einem Request-Handler
// Erwartet einen HTTP-POST-Request mit Content-Type: application/x-www-form-urlencoded
[$postData, $filesData] = request_parse_body();

echo 'Name: ' . htmlspecialchars($postData['name'] ?? '(nicht angegeben)') . PHP_EOL;
echo 'E-Mail: ' . htmlspecialchars($postData['email'] ?? '(nicht angegeben)') . PHP_EOL;

if (!empty($filesData)) {
    foreach ($filesData as $field => $file) {
        echo 'Hochgeladene Datei im Feld "' . htmlspecialchars($field) . '": ' . htmlspecialchars($file['name']) . PHP_EOL;
    }
}

Name: Max Mustermann E-Mail: max@example.com

Parsen mit benutzerdefinierten Limits

<?php
// Eigene Limits für diesen speziellen Request-Handler
$options = [
    'post_max_vars' => 10,       // Maximal 10 POST-Felder
    'max_file_uploads' => 2,     // Maximal 2 Datei-Uploads
];

try {
    [$postData, $filesData] = request_parse_body($options);

    echo 'Anzahl POST-Felder: ' . count($postData) . PHP_EOL;
    echo 'Anzahl Uploads: ' . count($filesData) . PHP_EOL;
} catch (\ValueError $e) {
    // Fehler bei ungültigen Optionen
    echo 'Ungültige Optionen: ' . $e->getMessage() . PHP_EOL;
} catch (\RuntimeException $e) {
    // Fehler beim Parsen des Body
    echo 'Fehler beim Parsen: ' . $e->getMessage() . PHP_EOL;
}

Anzahl POST-Felder: 3 Anzahl Uploads: 1

// Wichtig · Fallstricke

Sicherheitshinweis: Verwende die zurückgegebenen Daten aus request_parse_body() niemals ungeprüft. Alle Eingaben müssen wie bei $_POST und $_FILES validiert und sanitisiert werden, bevor sie weiterverarbeitet oder in einer Datenbank gespeichert werden.

Doppeltes Parsen: Wenn PHP den Request-Body bereits automatisch geparst und $_POST befüllt hat (was im Standard-Webserver-Betrieb der Fall ist), liest request_parse_body() erneut aus dem Eingabe-Stream. Je nach SAPI und Konfiguration kann der Stream zu diesem Zeitpunkt bereits erschöpft sein. In solchen Fällen empfiehlt es sich, die Funktion früh im Request-Lifecycle aufzurufen, bevor der Body anderweitig konsumiert wird.

PHP 8.4: Diese Funktion steht erst ab PHP 8.4.0 zur Verfügung. Für ältere PHP-Versionen muss der Body manuell über php://input gelesen und geparst werden.

Siehe auch

php://input $_POST $_FILES parse_str $_GET