4. Lectura de Cabeceras HTTP y Captura de Payloads JSON con php://input
Aprende por qué $_POST no captura datos en peticiones PUT o payloads JSON y cómo leer el flujo de entrada crudo con file_get_contents("php://input").
¿Por qué $_POST está vacío al recibir JSON?
Muchos programadores formados en desarrollo tradicional de formularios intentan leer datos de una API REST haciendo $email = $_POST['email']; y descubren con sorpresa que $_POST llega completamente vacío (array()).
El motivo es arquitectónico: PHP solo puebla automáticamente la superglobal $_POST cuando la petición llega con el método POST y con las cabeceras de formulario web clásico:
application/x-www-form-urlencodedmultipart/form-data
Cuando una aplicación moderna (React, Axios, Postman o Flutter) envía datos en una API REST, utiliza el estándar Content-Type: application/json tanto en POST como en PUT o PATCH. PHP no parsea este formato por defecto en $_POST.
La Solución Nativa: El Flujo Crudo php://input
php://input es un flujo de solo lectura que permite acceder a los bytes crudos recibidos en el cuerpo (body) de la petición HTTP:
// 1. Leer el cuerpo de la petición como texto plano
$jsonCrudo = file_get_contents('php://input');
// 2. Decodificar el texto JSON a un array asociativo en PHP
$datos = json_decode($jsonCrudo, true);
// 3. Validar si la sintaxis del JSON era válida
if (json_last_error() !== JSON_ERROR_NONE) {
http_response_code(400); // 400 Bad Request
echo json_encode(['error' => 'Sintaxis JSON malformada o inválida']);
exit;
}
⚡ Función Robusta para Capturar y Validar el Body JSON en PHP
Ejemplo de lector de peticiones JSON con validación de Content-Type y errores de sintaxis:
<?php
declare(strict_types=1);
/**
* Lee y valida el cuerpo JSON de la petición HTTP entrante.
*
* @return array<string, mixed> Array asociativo con los datos enviados
*/
function obtenerPayloadJson(): array
{
// 1. Verificar que la cabecera Content-Type declare formato JSON
$contentType = $_SERVER['CONTENT_TYPE'] ?? $_SERVER['HTTP_CONTENT_TYPE'] ?? '';
if (!str_contains(strtolower($contentType), 'application/json')) {
http_response_code(415); // 415 Unsupported Media Type
echo json_encode([
'error' => 'Se requiere cabecera Content-Type: application/json'
]);
exit;
}
// 2. Leer el flujo de entrada crudo
$cuerpo = file_get_contents('php://input');
if (empty($cuerpo)) {
http_response_code(400);
echo json_encode(['error' => 'El cuerpo de la petición no puede estar vacío']);
exit;
}
// 3. Parsear JSON a array asociativo
$datos = json_decode($cuerpo, true);
if (json_last_error() !== JSON_ERROR_NONE) {
http_response_code(400);
echo json_encode([
'error' => 'JSON inválido: ' . json_last_error_msg()
]);
exit;
}
return $datos;
}
// Ejemplo de uso:
// $payload = obtenerPayloadJson();
// echo "Recibido usuario: " . $payload['nombre'];
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección¿Por qué la superglobal $_POST llega vacía cuando un cliente envía una petición con "Content-Type: application/json"?
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.🚀 ¿Quieres dominar APIs RESTful con PHP Puro, JSON & JWT y crear proyectos reales?
Aprende arquitectura limpia, desarrollo web moderno, buenas prácticas y despliegue en producción con nuestro Bootcamp Fullstack Developer con mentorías en vivo.