Codificación JSON con PHP

JSON (JavaScript Object Notation) es un formato de intercambio de datos ligero y basado en texto, fácil de leer para los humanos y fácil de analizar para las máquinas. Es el formato de facto para enviar datos entre un servidor y el navegador, para REST APIs y para archivos de configuración. En PHP, json_encode() recibe un valor PHP — un escalar, un array o un objeto — y devuelve su representación JSON como string.

Esta página cubre la sintaxis, los $flags más útiles, cómo se mapean los tipos PHP a JSON y cómo detectar errores de codificación. Para hacer lo contrario (string JSON → valor PHP) véase json_decode().

Sintaxis

json_encode(mixed $value, int $flags = 0, int $depth = 512): string|false

Devuelve un string codificado en JSON en caso de éxito, o false en caso de fallo (por ejemplo, cuando la entrada contiene UTF-8 malformado).

Parámetros

• $value — el valor a codificar. Puede ser cualquier tipo excepto un resource. Todos los datos de tipo string deben ser UTF-8 válido.
• $flags (opcional) — una máscara de bits que personaliza la salida. Los más comunes:
  • JSON_PRETTY_PRINT — añade espacios en blanco e indentación para que la salida sea legible.
  • JSON_UNESCAPED_UNICODE — mantiene los caracteres multibyte (é, ñ, 日) literales en lugar de escaparlos como \uXXXX.
  • JSON_UNESCAPED_SLASHES — deja / sin escapar (PHP lo escapa como \/ por defecto).
  • JSON_FORCE_OBJECT — codifica un array secuencial como un objeto JSON ({}) en lugar de un array ([]).
  • JSON_THROW_ON_ERROR — lanza una JsonException en caso de fallo en lugar de devolver false (PHP 7.3+).
  • Combina flags con el operador OR a nivel de bits: JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE.
• $depth (opcional) — la profundidad máxima de anidamiento. Debe ser mayor que 0. El valor por defecto de 512 es suficiente para datos normales.

Cómo se mapean los tipos PHP a JSON

Ejemplos

Codificación de un array

Un array asociativo PHP se convierte en un objeto JSON; las claves se convierten en nombres de propiedades.

Salida:

{"a":1,"b":2,"c":3,"d":4,"e":5}

Codificación de un objeto

Las propiedades públicas de un objeto se codifican; las propiedades private y protected se omiten.

Salida:

{"name":"John Doe","age":35,"city":"New York"}

Formateo legible y Unicode sin escapar

Por defecto la salida es compacta, en una sola línea, y los caracteres no ASCII se escapan (de modo que é se convierte en é). Dos flags hacen la salida legible para humanos:

<?php

$data = [
    "name"  => "Café",
    "tags"  => ["php", "json"],
    "price" => 9.50,
];

echo json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);

?>

Salida:

{
    "name": "Café",
    "tags": [
        "php",
        "json"
    ],
    "price": 9.5
}

Ten en cuenta que 9.50 se emite como 9.5 — los ceros finales de los floats se eliminan. Usa JSON_PRESERVE_ZERO_FRACTION si necesitas que 9.0 siga siendo un float en lugar de convertirse en 9.

Manejo de errores

Si json_encode() devuelve false, algo salió mal — con mayor frecuencia UTF-8 malformado en un string. Comprueba json_last_error_msg(), o pasa JSON_THROW_ON_ERROR para obtener una excepción en su lugar.

<?php

$value = json_encode("\xB1\x31"); // invalid UTF-8 byte sequence

if ($value === false) {
    echo "Encoding failed: " . json_last_error_msg();
}

?>

Salida:

Encoding failed: Malformed UTF-8 characters, possibly incorrectly encoded

Casos de uso comunes

• Devolver datos desde una API. Establece la cabecera y muestra el array codificado:

  header('Content-Type: application/json');
  echo json_encode(['status' => 'ok', 'items' => $items]);

  Copiar

• Almacenar datos estructurados en un archivo o en una columna de texto de una base de datos en lugar de serialize(). JSON es portable entre lenguajes; serialize() es exclusivo de PHP.

• Pasar datos a JavaScript renderizado en la página, ya que JSON válido es sintaxis de objeto JavaScript válida.

Conclusión

json_encode() convierte arrays y objetos PHP en un string JSON compacto y portable. Recurre a JSON_PRETTY_PRINT y JSON_UNESCAPED_UNICODE cuando una persona vaya a leer la salida, protégete contra entradas malformadas comprobando el valor de retorno o usando JSON_THROW_ON_ERROR, y recuerda que solo se codifican las propiedades públicas de los objetos. Para analizar JSON de vuelta a PHP, usa json_decode(); para una visión general más amplia, véase Trabajando con JSON en PHP.

Práctica