Tema 4 · Captura de Datos

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-urlencoded
  • multipart/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:

capturar-payload.php
Solo lectura
<?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
1 Pregunta
Pregunta 1
¿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.

🏛️ Autoría y Propiedad Intelectual: Obra educativa original de Juan Sebastián Amador para Kilopolis Academia, estructurada sobre las especificaciones y estándares abiertos del W3C, el estándar vivo de WHATWG y la documentación oficial de código abierto. © Todos los derechos reservados.