Referencia de Funciones JSON en PHP

JSON (JavaScript Object Notation) es un formato de intercambio de datos ligero y basado en texto. Debido a que es fácil de leer para las personas y trivial de analizar para las máquinas, se ha convertido en la forma predeterminada de enviar datos entre un servidor y un navegador, y entre servicios web (REST APIs).

PHP incluye un pequeño conjunto de funciones integradas — denominadas colectivamente la extensión JSON — que convierten valores PHP a texto JSON y viceversa. Esta página es una referencia rápida a esas funciones y las constantes de opción más útiles. Para un tutorial paso a paso, consulta PHP JSON.

¿Cuándo usaría JSON en PHP?

Recurrirás a estas funciones siempre que los datos deban salir de PHP como texto o llegar como texto:

• Devolver datos desde un endpoint de API (echo json_encode($data);).
• Leer el cuerpo de una solicitud o un archivo de configuración escrito en JSON.
• Almacenar un valor estructurado (por ejemplo, un array de configuraciones) en una sola columna de base de datos o clave de caché.
• Comunicarse con un servicio web de terceros que utiliza JSON.

La extensión JSON está habilitada de forma predeterminada en PHP 5.2 y versiones posteriores, y es parte del núcleo en PHP 8.0+, por lo que no se necesita instalación.

Funciones JSON

json_encode()

json_encode() serializa un valor PHP en una cadena con formato JSON.

<?php

$data = [
    "name"  => "Ada",
    "age"   => 36,
    "langs" => ["PHP", "JS"],
];

echo json_encode($data);

?>

Salida:

{"name":"Ada","age":36,"langs":["PHP","JS"]}

Observa cómo un array asociativo se convierte en un objeto JSON {}, mientras que un array de lista (["PHP","JS"]) se convierte en un array JSON []. Consulta la referencia completa en json_encode().

Formato de salida legible

Pasa la opción JSON_PRETTY_PRINT para que el resultado sea más legible:

<?php

$data = ["name" => "Ada", "langs" => ["PHP", "JS"]];

echo json_encode($data, JSON_PRETTY_PRINT);

?>

Salida:

{
    "name": "Ada",
    "langs": [
        "PHP",
        "JS"
    ]
}

json_decode()

json_decode() analiza una cadena JSON y la convierte en un valor PHP. Por defecto devuelve objetos (stdClass); pasa true como segundo argumento para obtener arrays asociativos en su lugar.

<?php

$json = '{"name":"Ada","age":36,"langs":["PHP","JS"]}';

// Decode as an associative array
$data = json_decode($json, true);

echo $data["name"];   // Ada
echo "\n";
echo $data["langs"][0]; // PHP

?>

Salida:

Ada
PHP

Consulta la referencia completa en json_decode().

Manejo de errores

json_encode() devuelve false y json_decode() devuelve null cuando algo sale mal (UTF-8 no válido, un error de sintaxis en la entrada, o una anidación más profunda que el límite de profundidad). Dado que null también es un valor decodificado válido, siempre verifica json_last_error() en lugar de comprobar únicamente si el resultado es null.

<?php

$bad = '{"name": "Ada", }';   // trailing comma is invalid JSON

$result = json_decode($bad, true);

if (json_last_error() !== JSON_ERROR_NONE) {
    echo "Invalid JSON: " . json_last_error_msg();
} else {
    echo "Decoded fine.";
}

?>

Salida:

Invalid JSON: Syntax error

En PHP 7.3+ puedes pasar el indicador JSON_THROW_ON_ERROR a ambas funciones para obtener una JsonException en lugar de inspeccionar el código de error manualmente.

Constantes de opción más comunes

Estas constantes de máscara de bits se pasan en el argumento $options de json_encode() (y algunas aplican a json_decode()):

• JSON_PRETTY_PRINT — formatea la salida con espacios en blanco e indentación.
• JSON_UNESCAPED_SLASHES — deja los caracteres / sin escapar (http:// en lugar de http:\/\/).
• JSON_UNESCAPED_UNICODE — mantiene los caracteres multibyte tal como están en lugar de escapes \uXXXX.
• JSON_THROW_ON_ERROR — lanza una JsonException en caso de error (PHP 7.3+).
• JSON_FORCE_OBJECT — emite siempre un objeto JSON, incluso para un array secuencial.

Combínalos con el operador OR a nivel de bits:

<?php

$data = ["site" => "https://www.w3docs.com", "name" => "café"];

echo json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);

?>

Salida:

{
    "site": "https://www.w3docs.com",
    "name": "café"
}

Temas relacionados

• PHP JSON — la introducción completa del tutorial.
• PHP Arrays y Arrays Asociativos — las estructuras que se corresponden más naturalmente con JSON.
• PHP Functions — cómo envolver encode/decode en tus propios helpers.

Práctica