YAML y PHP (II)

Ahora que ya tenemos instalada la extensión YAML para PHP, podemos manejar, desde este lenguaje, todo tipo de datos yaml, tanto para serializar datos de nuestro script en este formato, como para leer datos en este formato y convertirlos a variables que puedan ser usadas por nuestro script.

En este artículo nos vamos a centrar en la lectura de datos, bien a partir de un archivo en disco, o de un flujo que inyectemos en un script por otro medio. Esto nos permitirá establecer una conectividad entre un script y cualquier proceso de un proveedor externo que nos envíe información en YAML.

Una cosa que te va a llamar la atención es la forma en que PHP lee datos YAML. Verás que PHP estructura todos los datos que lee «de una tacada» en una matriz, tanto si son datos escalares como un arreglo. Esto puede inducir un poco a confusión al principio pero, una vez que sabes esto, y te familiarizas con la forma de trabajar, no hay ningún problema. Como ya es habitual, los códigos de ejemplo de este artículo te los dejo en un comprimido al final del mismo para que te los descargues.

LEER DATOS EN YAML

Existen dos formas de leer datos en YAML, según estos procedan de un fichero o de un flujo inyectado. El resultado final es el mismo. Por comodidad, vamos a empezar leyendo desde un fichero. Para ello, tenemos un archivo, llamado fichero_1.yml, cuyo contenido es la muestra de YAML que vimos en el primer artículo de esta serie. También tenemos un script, llamado leer_fichero_yaml_1.php, cuyo listado es el siguiente:

Como ves, es muy simple. La función yaml_parse_file() -que sólo está disponible si has instalado la extensión YAML- recibe, como argumento, el nombre (y, en su caso, la ruta) de un fichero YAML. Lo analiza y lo convierte en una matriz de datos asociativa, que puedes visualizar (cómo hacemos aquí) o manejar según tus necesidades. Ejecuta este script desde el navegador y verás la matriz de datos tal cómo queda: los datos escalares aparecen como elementos de primer nivel, y los arreglos aparecen con tantos niveles como tengamos.

Leer datos YAML desde un flujo inyectado tampoco tiene mayor complicación. En este caso empleamos la función yaml_parse(), tal como ves en el listado leer_inyectado_yaml_1.php:

Observa la primera parte del código. Parece que estamos haciendo algo muy similar a lo anterior, ya que leemos un fichero .yml, pero sólo lo parece. Si te fijas, el contenido de ese fichero se almacena en una variable de memoria y el fichero se cierra antes de hacer nada relativo a YAML. A eso nos referimos, en este contexto, con «un flujo inyectado». Tenemos el contenido YAML inyectado en una variable de memoria. Que proceda, como en este caso, de haber leído previamente un fichero no cambia nada el concepto. Podría proceder de un formulario, o de una llamada desde otra API, o de cualquier otra fuente. El hecho es que, una vez los datos están en una variable, la usamos como argumento de yaml_parse() y obtenemos la misma matriz que en el caso anterior.

Existe una variante de lectura de datos mediante un flujo, que permite leer los datos de un servidor remoto. Se trata de la función yaml_parse_url(). Esta recibe, como argumento, una URL en la que esperamos encontrar un recurso que contenga datos YAML. Es una funcionalidad muy empleada en intercambio de datos entre API’s de distintas aplicaciones. Sin embargo, es una función que, dependiendo del alojamiento donde se encuentre el script de lectura y el fichero YAML, puede no operar adecuadamente. Por ejemplo, desde una envoltura https no es posible leer directamente datos en http, siendo necesaria una capa intermedia como la que proporciona cUrl. Es un tema del que hablaremos en un artículo posterior en la serie HTTP Masters.

ATENCIÓN. Un punto muy importante, si necesitas recurrir, por cualquier razón, a yaml_parse_url(). El protocolo de la URL donde esté alojado en YAML es una envoltura que debe ser soportada por tu instalación de PHP. Para saber que envolturas soporta tu instalación, emplea var_dump(stream_get_wrappers());. Normalmente obtendrás una matriz similar a la siguiente:

Normalmente, esto cubre todas las necesidades que puedas tener. No obstante, puedes registrar nuevas envolturas, con la función stream_wrapper_register(). Este tema se sale del contexto de este artículo, y lo comentaremos con más detenimiento en su momento.

ARGUMENTOS OPCIONALES

Las funciones que hemos visto tienen una sintaxis muy similar entre sí y, todas ellas, soportan, además de un primer argumento obligatorio, otros tres opcionales. Vamos a verlos en este apartado.

LEER DOCUMENTOS INDIVIDUALMENTE

En primer lugar, debes saber que, en un mismo fichero YAML puedes tener dos o más documentos (flujos de datos). En ese caso, cada flujo de datos se inicia con --- y se finaliza con ... (esto aparece reflejado en la sintaxis de YAML, en el artículo de este enlace). Suponte que tenemos una variante de nuestro fichero YAML, dividida en dos flujos de datos, así:

Ahora vamos a usar la función yaml_parse_file() con un segundo argumento, como vemos en leer_fichero_yaml_2.php:

Los flujos de datos se numeran como los elementos de una matriz indexada. Sabiendo esto, y leyendo los comentarios del código, ejecútalo para ver el resultado.

EL SEGUNDO ARGUMENTO DE LECTURA

El segundo argumento de lectura no le vamos a dar, por ahora, un uso práctico. Baste saber que debe ser una variable con el valor 0. No el valor 0, sino una variable con dicho valor.

FUNCIONES DE CALLBACK

Como tercer argumento opcional podemos crear una función de callback personalizada que nos procese, del modo que deseemos, determinados datos del YAML antes de devolverlos. En este apartado vamos a ver cómo hacer esto. Sobre el fichero YAML que estamos usando, vamos a suponer que queremos modificar las fechas de los eventos, de modo que aparezcan en forma literal. Así, 20/10/1985 debería aparecer como 20 de octubre de 1985, por ejemplo.

Para ello, lo primero que tenemos que hacer es modificar el fichero YAML, añadiendo una etiqueta precedida de ! a los datos que queremos que sean afectados por esta transformación. Las fechas de los eventos, que ahora aparecen como fecha: '11/06/2018' las pondremos como fecha: !dia '11/06/2018'. Observa como hemos dejado el YAML, llamado fichero_3.yml:

Observa las líneas destacadas, y compáralas con las reglas de sintaxis de este artículo.

Ahora, en el PHP que lee este fichero YAML, lo primero que hacemos es declarar la función de callback que recibirá estas fechas, las procesará y las devolverá en formato literal, así:

Y ahora llega el momento de leer el fichero YAML. el tercer argumento opcional es una matriz con un elemento. La clave es la etiqueta de referencia que le pusimos a las fechas en el YAML. El valor es el nombre de la función de callback, así:

Y ya está. Como siempre, comprueba el resultado. Todos los archivos necesarios para seguir este artículo los tienes para descargar en este enlace.

   

Deja un comentario