PHP JSON

JSON (JavaScript Object Notation) es un formato de intercambio de datos ligero y basado en texto. Es la forma más común de enviar y recibir datos entre un backend PHP y un navegador, una aplicación móvil u otro servicio web (la mayoría de las APIs REST usan JSON). Esta guía cubre todo lo que necesitas para trabajar con JSON en PHP: convertir datos PHP a JSON con json_encode, convertir JSON de vuelta a datos PHP con json_decode, formatear la salida y manejar errores de forma segura.

PHP incluye soporte para JSON en su núcleo (la extensión ext-json está incluida y habilitada por defecto desde PHP 8.0), por lo que no hay nada que instalar.

Cómo se ve JSON

JSON representa datos como pares clave-valor dentro de objetos ({ }) y listas ordenadas dentro de arrays ([ ]). Los valores pueden ser cadenas, números, booleanos, null, arrays u objetos anidados:

{
  "name": "John",
  "age": 30,
  "active": true,
  "roles": ["admin", "editor"]
}

Las dos funciones que usarás casi siempre son:

• json_encode($value) — valor PHP → cadena JSON (serializar).
• json_decode($json) — cadena JSON → valor PHP (deserializar).

Codificación: PHP a JSON con json_encode

json_encode() convierte un valor PHP — típicamente un array u objeto — en una cadena JSON.

Codificación de un array asociativo

Un array asociativo se convierte en un objeto JSON, mientras que un array indexado (claves enteras secuenciales comenzando en 0) se convierte en un array JSON:

<?php

echo json_encode(["red", "green", "blue"]);
// ["red","green","blue"]

?>

Formatear la salida

Por defecto, json_encode produce JSON compacto en una sola línea, lo cual es ideal para enviar por la red. Cuando quieras una salida legible por humanos (para registros o depuración), pasa el indicador JSON_PRETTY_PRINT. Los indicadores se combinan con el operador bit a bit |:

<?php

$data = [
    "user" => ["name" => "Jane", "roles" => ["admin", "editor"]],
    "active" => true,
];

echo json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);

?>

Esto imprime JSON con una indentación clara:

{
    "user": {
        "name": "Jane",
        "roles": [
            "admin",
            "editor"
        ]
    },
    "active": true
}

Otros indicadores útiles: JSON_UNESCAPED_SLASHES (mantiene / en lugar de \/) y JSON_UNESCAPED_UNICODE (mantiene caracteres como é en lugar de é).

Decodificación: JSON a PHP con json_decode

json_decode() convierte una cadena JSON de vuelta en un valor PHP. Por defecto devuelve objetos, pero pasar true como segundo argumento devuelve arrays asociativos en su lugar — que generalmente son más fáciles de recorrer:

Sin el argumento true, obtienes un objeto stdClass y accedes a los valores con la notación de flecha -> en lugar de [ ]:

Usa true cuando quieras un array; omítelo cuando prefieras la sintaxis de objeto. Ambos contienen los mismos datos.

Codificar un objeto personalizado

json_encode también funciona con objetos. Cuando necesitas construir una estructura JSON sobre la marcha, el objeto stdClass vacío te permite añadir propiedades dinámicamente. (Para clases completas, consulta Clases y Objetos PHP.)

Las propiedades públicas de cualquier objeto se incluyen automáticamente; las propiedades privadas y protegidas se omiten a menos que la clase implemente la interfaz JsonSerializable.

Manejo de errores

El análisis de JSON puede fallar — una cadena mal formada, una comilla sin cerrar o una coma final romperán la decodificación. Cuando json_decode falla, devuelve null, por lo que debes distinguir un valor null real de un error. Comprueba json_last_error() (o lee json_last_error_msg() para obtener un mensaje legible por humanos):

<?php

$badJson = '{invalid}';
$result = json_decode($badJson);

if (json_last_error() !== JSON_ERROR_NONE) {
    echo "JSON error: " . json_last_error_msg();
    // JSON error: Syntax error
}

?>

Desde PHP 7.3 puedes pasar el indicador JSON_THROW_ON_ERROR para que ambas funciones lancen una JsonException, lo cual encaja perfectamente en bloques try/catch:

<?php

try {
    $data = json_decode('{invalid}', true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo "Could not parse JSON: " . $e->getMessage();
}

?>

Nota: json_decode tiene un límite de profundidad (512 niveles por defecto, el tercer argumento). JSON muy profundamente anidado fallará con un error JSON_ERROR_DEPTH a menos que lo aumentes.

Caso de uso común: leer el cuerpo de una solicitud JSON

Cuando un cliente envía JSON a un endpoint PHP (como hacen la mayoría de las APIs), el cuerpo llega como entrada sin procesar en lugar de $_POST. Léelo con php://input y decodifícalo:

<?php

$body = file_get_contents("php://input");
$data = json_decode($body, true);

// echo a JSON response back to the client
header("Content-Type: application/json");
echo json_encode(["received" => $data]);

?>

Conclusión

JSON es el formato estándar para el intercambio de datos en las aplicaciones web modernas, y PHP lo hace sencillo de usar:

• Usa json_encode para convertir arrays y objetos en JSON; añade JSON_PRETTY_PRINT para una salida legible.
• Usa json_decode para convertir JSON de vuelta a PHP — pasa true para obtener un array, omítelo para obtener un objeto.
• Siempre comprueba los errores con json_last_error() o JSON_THROW_ON_ERROR antes de confiar en los datos decodificados.

Con estas herramientas podrás enviar y recibir JSON de forma segura entre tu código PHP, bases de datos, navegadores y servicios web externos.

Práctica