Comprensión de la función json_decode en PHP

La función json_decode en PHP convierte una cadena con formato JSON en un valor PHP nativo que puedes leer y manipular. Es la contraparte de json_encode, que realiza la operación inversa (valor PHP → cadena JSON). Se recurre a json_decode cuando los datos llegan como texto y necesitas trabajar con ellos: una respuesta de una REST API, el payload de un webhook, un archivo de configuración o una columna almacenada en una base de datos.

Este capítulo cubre la firma de la función, la diferencia entre decodificar a un objeto y a un array asociativo, cómo se comportan los datos anidados, las opciones de profundidad y flags, y la forma correcta de manejar entradas no válidas.

¿Qué es JSON?

JSON (JavaScript Object Notation) es un formato de intercambio de datos ligero, basado en texto, fácil de leer para los humanos y de analizar para las máquinas. Representa datos como pares clave-valor (objetos, escritos {}) y listas ordenadas (arrays, escritos []), con cadenas, números, booleanos y null como valores escalares. Como casi todos los lenguajes pueden producirlo y consumirlo, JSON se ha convertido en el formato predeterminado para las APIs web. Consulta la descripción general de PHP y JSON para tener una visión más amplia.

Sintaxis

json_decode(string $json, ?bool $associative = null, int $depth = 512, int $flags = 0): mixed

Parámetro	Propósito
`$json`	La cadena JSON a decodificar. Debe ser UTF-8 válido.
`$associative`	`true` → devuelve arrays asociativos; `false`/`null` → devuelve objetos `stdClass`.
`$depth`	Profundidad máxima de anidamiento permitida (por defecto `512`). La decodificación falla si la entrada es más profunda.
`$flags`	Máscara de bits de opciones, p. ej. `JSON_THROW_ON_ERROR`, `JSON_BIGINT_AS_STRING`.

La función devuelve el valor decodificado (array, stdClass, string, int, float, bool o null), o null en caso de fallo.

Decodificar una cadena JSON

El uso más común es decodificar un objeto JSON. Pasa true como segundo argumento para obtener un array asociativo PHP.

Ejemplo de la función json_decode en PHP

php— editable, runs on the server

Aquí $json representa el nombre, la edad y la ciudad de una persona. Con true, json_decode construye un array PHP, por lo que el resultado es:

Array
(
    [name] => John
    [age] => 30
    [city] => New York
)

Luego puedes leer los valores con sintaxis de array, p. ej. $array['name']. Consulta arrays asociativos para obtener más información sobre esta estructura de datos.

Uso del segundo parámetro

El segundo parámetro de la función json_decode es opcional, pero se utiliza con frecuencia para controlar el tipo de la variable devuelta. Si el segundo parámetro se establece en true, json_decode devolverá un array. Si el segundo parámetro se establece en false (el valor predeterminado), json_decode devolverá un objeto.

Ejemplo de la función json_decode en PHP con objetos

php— editable, runs on the server

Cuando $associative es false (u omitido), json_decode devuelve un objeto stdClass. Los valores se leen con la sintaxis de propiedad de objeto $object->name, $object->age, etc. Usa esta forma cuando prefieras el acceso al estilo de objeto o cuando el resultado vaya a pasarse a código que espera objetos (consulta clases y objetos PHP).

Decodificar JSON anidado

El JSON del mundo real suele estar anidado. json_decode maneja el anidamiento automáticamente: cada nivel se convierte en un array anidado (con true) o en un objeto anidado (con false).

<?php

$json = '{"user":{"name":"John","roles":["admin","editor"]}}';
$data = json_decode($json, true);

echo $data['user']['name'];      // John
echo "\n";
echo $data['user']['roles'][0];  // admin

?>

Los objetos JSON internos se convierten en arrays internos, y los arrays JSON ([...]) se convierten en arrays indexados de PHP sobre los que puedes iterar con foreach.

Manejo de errores

Si la cadena de entrada pasada a json_decode no es JSON válido, la función devuelve null. Sin embargo, null también es un valor JSON válido, por lo que comprobar if ($array === null) no puede distinguir entre un error de decodificación y una decodificación exitosa del literal null. Para manejar los errores correctamente, comprueba json_last_error() o usa el flag JSON_THROW_ON_ERROR (PHP 7.3+).

Manejo de errores de json_decode en PHP

php— editable, runs on the server

La cadena anterior tiene una comilla de cierre faltante, por lo que json_last_error() no es JSON_ERROR_NONE y el mensaje explica qué salió mal.

A partir de PHP 7.3, la opción más limpia es el flag JSON_THROW_ON_ERROR, que lanza una JsonException en lugar de devolver null silenciosamente:

<?php

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

?>

Esto te permite manejar entradas malformadas con bloques try/catch estándar en lugar de comprobar el resultado manualmente después de cada llamada.

Funciones relacionadas

json_encode — convierte un valor PHP en una cadena JSON.
PHP y JSON — descripción general del trabajo con JSON en PHP.
Referencia JSON de PHP — lista completa de las funciones y constantes JSON de PHP.

Conclusión

La función json_decode en PHP es una herramienta potente para trabajar con datos JSON. Es rápida, confiable y fácil de usar. Al comprender los detalles de json_decode y su segundo parámetro, puedes decodificar cadenas JSON con confianza y usar los datos resultantes en tus aplicaciones PHP.

Práctica

¿Qué hace la función json_decode() en PHP?

Convierte una cadena JSON en una variable PHP.Decodifica datos codificados en base64.Cambia los caracteres HTML a sus entidades.Permite pasar true como segundo argumento para convertir objetos JSON en arrays asociativos.