json_encode en PHP: UTF-8, errores y forma del resultado

Codificar datos, no concatenar comillas

json_encode convierte valores PHP en una representación JSON. Si concatenas comillas manualmente, un salto de línea o una comilla dentro de un nombre puede romper la respuesta. Usa datos y deja que el codificador resuelva esos caracteres.

$datos = ['nombre' => 'Línea', 'cantidad' => 2];
echo json_encode($datos, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
echo PHP_EOL;
// {"nombre":"Línea","cantidad":2}

JSON_THROW_ON_ERROR, disponible desde PHP 7.3, permite tratar fallos como excepciones. Para una API, registra el detalle técnico en el servidor y devuelve un mensaje público adecuado; no reveles rutas o credenciales dentro de una excepción.

La forma de las claves cambia el JSON

Una lista con índices consecutivos desde cero se codifica como array JSON. Si eliminas un elemento intermedio, puedes terminar con un objeto cuyas claves son números escritos como texto. Reindexa con array_values cuando el contrato de la API exija una lista.

$lista = ['a', 'b', 'c'];
unset($lista[1]);
echo json_encode($lista), PHP_EOL; // {"0":"a","2":"c"}
echo json_encode(array_values($lista)), PHP_EOL; // ["a","c"]

No reindexes un mapa por accidente: perder sus claves puede ser un error más grave que cambiar la presentación. Decide de antemano si un campo representa una lista o un diccionario.

UTF-8 y salida HTTP

Las cadenas que se codifican deben tener una codificación válida. No utilices sustitución silenciosa de caracteres como primera solución a un origen de datos mal configurado. Revisa archivo, conexión y transformación que produjeron el texto.

En una respuesta JSON, envía Content-Type: application/json; charset=UTF-8 antes de escribir el cuerpo. Un aviso PHP o un texto de depuración anterior al JSON también rompe la respuesta, aunque el resultado de json_encode sea correcto. Para incrustar datos dentro de HTML o JavaScript, utiliza además una estrategia segura para ese contexto; servir JSON como una respuesta independiente evita varias confusiones.

Referencia 1

Referencia 2