Obtener el objeto JSON de la URL en PHP

Esta guía explica cómo obtener una respuesta JSON en PHP, decodificarla para convertirla en datos utilizables y elegir entre file_get_contents() y cURL. El ejemplo con el envoltorio de flujo usa una URL de datos autónoma; el ejemplo con cURL utiliza el endpoint de publicaciones de JSONPlaceholder.

Obtener JSON con file_get_contents()

La función file_get_contents() puede leer una URL remota si está habilitada la opción allow_url_fopen de PHP. Suele estar habilitada de forma predeterminada, pero el proveedor de alojamiento puede controlarla. Si se rechaza la lectura de una URL, comprueba la configuración activa de PHP. php.ini es el archivo de configuración que debes modificar si administras la instalación de PHP; una llamada como ini_set('allow_url_fopen', '1') no puede habilitar esta opción de forma fiable durante la ejecución, porque se trata de una directiva del sistema.

La solicitud devuelve el cuerpo de la respuesta como una cadena. Pasa esa cadena a json_decode() para convertir el JSON válido en datos de PHP. Este ejemplo autónomo obtiene JSON con el envoltorio de URL data:// de PHP, por lo que puede mostrar una lectura correcta sin depender de un servicio externo. Para una API HTTP, sustituye $url por un endpoint como https://jsonplaceholder.typicode.com/posts/1:

Ejecuta este ejemplo:

El código y las etiquetas o salidas visibles de esta sección se mantienen en inglés.

<?php
$url = 'data://text/plain,%7B%22title%22%3A%22PHP%20JSON%20fetch%20works.%22%7D';
$json = file_get_contents($url);
$post = json_decode($json);
echo $post->title, PHP_EOL;

PHP JSON fetch works.

Para un endpoint HTTP, se siguen los mismos pasos: obtener el cuerpo de la respuesta, decodificar el JSON y acceder a la propiedad title. Si falla la lectura remota, se devuelve false; comprueba ese resultado antes de decodificar, como se muestra en la sección sobre cómo gestionar errores.

Obtener JSON con PHP cURL

Usa la extensión cURL de PHP cuando esté disponible y necesites controlar mejor las opciones de la solicitud, los encabezados, los tiempos de espera o la gestión del estado HTTP. La extensión debe estar instalada y habilitada. CURLOPT_RETURNTRANSFER hace que curl_exec() devuelva el cuerpo de la respuesta como una cadena en lugar de escribirlo en la salida. Cierra siempre el identificador después de la solicitud.

Este ejemplo realiza la solicitud a JSONPlaceholder y decodifica la respuesta como un objeto. Imprime el título solo si la solicitud se completa correctamente y la respuesta incluye ese campo; si cURL no está disponible, indica el requisito previo en lugar de presentar esa ruta como una obtención correcta:

El código y las etiquetas o salidas visibles de esta sección se mantienen en inglés.

<?php
$url = 'https://jsonplaceholder.typicode.com/posts/1';
if (!function_exists('curl_init')) {
    echo "Enable the PHP cURL extension first.", PHP_EOL;
} else {
    $curl = curl_init($url);
    if ($curl === false) {
        echo "Could not initialize cURL.", PHP_EOL;
    } else {
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
        $response = curl_exec($curl);
        if ($response === false) {
            $error = curl_error($curl);
            curl_close($curl);
            echo "Request failed: ", $error, PHP_EOL;
        } else {
            curl_close($curl);
            $post = json_decode($response);
            if (is_object($post) && isset($post->title)) {
                echo $post->title, PHP_EOL;
            } else {
                echo "The response did not contain a title.", PHP_EOL;
            }
        }
    }
}

La URL se pasa a curl_init(), que inicializa el identificador para esa dirección. curl_exec() realiza la solicitud; después, la respuesta se puede decodificar igual que la respuesta del envoltorio de flujo. Este ejemplo requiere que el endpoint sea accesible y que esté instalada la extensión cURL de PHP; el mensaje sobre el requisito previo no indica que se haya obtenido la respuesta correctamente.

Decodificar la respuesta JSON

De forma predeterminada, json_decode() devuelve los objetos JSON como objetos de PHP, así que se accede a un campo como title con $post->title. Si prefieres matrices asociativas, pasa true como segundo argumento: json_decode($response, true). Después, accede al mismo campo con $post['title']. Mantén coherentes el modo de decodificación y la sintaxis de acceso. En JSON anidado, sigue cada propiedad del objeto o clave de matriz en el nivel correspondiente.

Una solicitud HTTP correcta no garantiza que la respuesta contenga JSON válido. El servidor podría devolver una página de error HTML u otro cuerpo que no se pueda decodificar. Además, al decodificar el valor JSON válido null, se obtiene null en PHP; por eso, consulta json_last_error() si necesitas distinguir ese valor de un error de decodificación.

Gestionar errores de solicitud y decodificación

Con file_get_contents(), una lectura fallida devuelve false y puede generar una advertencia de PHP. Suprime esa advertencia solo si vas a gestionar el error por tu cuenta y, antes de llamar a json_decode(), comprueba que el resultado no sea false. Después de decodificar, consulta json_last_error() para no confundir un fallo de transporte con una respuesta que contiene JSON no válido. Este ejemplo autónomo lee JSON mal formado desde una URL de datos local; sustituye $url por tu endpoint para gestionar su respuesta:

El código y las etiquetas o salidas visibles de esta sección se mantienen en inglés.

<?php
$url = 'data://text/plain,%7Binvalid';
$json = @file_get_contents($url);

if ($json === false) {
    echo "Request failed: could not read the URL.", PHP_EOL;
} else {
    $data = json_decode($json);
    if (json_last_error() !== JSON_ERROR_NONE) {
        echo "JSON decoding failed: ", json_last_error_msg(), PHP_EOL;
    } else {
        echo "JSON decoded successfully.", PHP_EOL;
    }
}

Las dos ramas indican fallos distintos: la primera significa que PHP no pudo leer la URL; la segunda, que recibió un cuerpo que no es JSON válido. Con un endpoint real, consulta también el registro de errores de PHP si falla la lectura y verifica que allow_url_fopen esté habilitado y que se pueda acceder al endpoint.

Con cURL, comprueba si curl_exec() devolvió false antes de intentar decodificar el cuerpo. En ese caso, llama a curl_error($curl) antes de cerrar el identificador para obtener el error de transporte. Una solicitud cURL completada también puede recibir un estado HTTP de error; si necesitas gestionar el estado, consulta curl_getinfo($curl, CURLINFO_HTTP_CODE). Cierra siempre el identificador después de recopilar la respuesta y los diagnósticos.

Después de cualquiera de las solicitudes, consulta json_last_error() tras llamar a json_decode() si el cuerpo podría no ser JSON. Un valor distinto de cero indica un problema de decodificación; json_last_error_msg() proporciona una descripción. Mantén separados los fallos de transporte y los de decodificación para que el diagnóstico señale la etapa que falló.

Elegir un método

Elige file_get_contents() para una lectura sencilla cuando esté habilitado allow_url_fopen y baste con el comportamiento predeterminado del envoltorio de flujo. Elige cURL si la solicitud requiere encabezados personalizados, tiempos de espera, inspección del estado u otras opciones de transferencia, y asegúrate de que esté disponible la extensión cURL de PHP. En ambos casos, valida el resultado de la solicitud antes de decodificar y gestiona la decodificación JSON por separado.