El componente YAML carga y vuelca archivos YAML.
El componente YAML de Symfony2 analiza cadenas YAML para convertirlas en arreglos PHP. También es capaz de convertir arreglos PHP a cadenas YAML.
YAML, YAML no es un lenguaje de marcado, es un estándar para la serialización de datos amigable con los humanos para todos los lenguajes de programación. YAML es un formato ideal para tus archivos de configuración. Los archivos YAML son tan expresivos como los archivos XML y tan fáciles de leer como los archivos INI.
El componente YAML de Symfony2 implementa la versión 1.2 de la especificación YAML.
Puedes instalar el componente de varias maneras diferentes:
Uno de los objetivos del componente YAML de Symfony es encontrar el balance adecuado entre características y velocidad. Es compatible con las características necesarias para manipular archivos de configuración.
Este exporta un analizador real y es capaz de analizar un gran subconjunto de especificaciones YAML, para todas tus necesidades de configuración. También significa que el analizador es bastante robusto, fácil de entender, y lo suficientemente simple como para ampliarlo.
Cada vez que tienes un problema de sintaxis con tus archivos YAML, la biblioteca genera un útil mensaje de ayuda con el nombre y número de línea donde está el problema. Lo cual facilita mucho la depuración.
También es capaz de volcar arreglos de PHP a YAML con apoyo a objetos, y el nivel de configuración en línea es bastante bueno.
Es compatible con la mayoría de los tipos YAML integrados como fechas, números enteros, octales, booleanos, y mucho más...
Completa compatibilidad para referencias, alias y completa fusión de claves. No repitas tú mismo haciendo referencia a segmentos de configuración comunes.
El componente YAML de Symfony2 es muy simple y consiste de dos clases principales: una analiza cadenas YAML (Symfony\Component\Yaml\Parser), y la otra vuelca un array PHP en una cadena YAML (Symfony\Component\Yaml\Dumper).
Además de estas dos clases, la clase Symfony\Component\Yaml\Yaml actúa como un delgado contenedor que simplifica los usos más comunes.
El método parse() analiza una cadena YAML y la convierte en un arreglo PHP:
use Symfony\Component\Yaml\Parser;
$yaml = new Parser();
$value = $yaml->parse(file_get_contents('/path/to/file.yml'));
Si ocurre un error durante el análisis, el analizador lanza una excepción Symfony\Component\Yaml\Exception\ParseException que indica el tipo de error y la línea en la cadena YAML original en la que ocurrió el error:
use Symfony\Component\Yaml\Exception\ParseException;
try {
$value = $yaml->parse(file_get_contents('/path/to/file.yml'));
} catch (ParseException $e) {
printf("Unable to parse the YAML string: %s", $e->getMessage());
}
Truco
Debido a que el analizador es reentrante, puedes utilizar el mismo objeto analizador para cargar diferentes cadenas YAML.
Al cargar un archivo YAML, a veces es mejor usar el contenedor del método parse():
use Symfony\Component\Yaml\Yaml;
$yaml = Yaml::parse('/path/to/file.yml');
El método estático parse() toma una cadena YAML o un archivo que contiene YAML. Internamente, llama al método parse(), pero mejora el error si algo sale mal, añadiendo el nombre del archivo al mensaje.
Nuevo en la versión 2.1: El método Yaml::enablePhpParsing() es nuevo en Symfony 2.1. Antes de 2.1, PHP siempre se ejecuta al llamar a la función parse().
De manera predeterminada, si incluyes PHP dentro de un archivo YAML, no se va a analizar. Si quiere que PHP se analice, debes llamar a Yaml::enablePhpParsing() antes de analizar el archivo para activar ese modo. Si sólo deseas permitir código PHP para un único archivo YAML, asegúrate de desactivar el intérprete PHP después de analizar ese archivo llamando a Yaml::$enablePhpParsing = false;, ($enablePhpParsing es una propiedad pública).
El método dump() vuelca cualquier arreglo PHP en su representación YAML:
use Symfony\Component\Yaml\Dumper;
$array = array(
'foo' => 'bar',
'bar' => array('foo' => 'bar', 'bar' => 'baz')
);
$dumper = new Dumper();
$yaml = $dumper->dump($array);
file_put_contents('/path/to/file.yml', $yaml);
Nota
Por supuesto, el vertedor YAML de Symfony2 no es capaz de volcar recursos. Por otra parte, aun y cuando el vertedor es capaz de volcar objetos PHP, se considera como una función No admitida.
Si ocurre un error durante el volcado, el analizador lanza una excepción Symfony\Component\Yaml\Exception\DumpException.
Si sólo necesitas volcar un arreglo, puedes utilizar el método estático dump():
use Symfony\Component\Yaml\Yaml;
$yaml = Yaml::dump($array, $inline);
El formato YAML admite dos tipos de representación de arreglos, la ampliada, y en línea. Por omisión, el vertedor utiliza la representación en línea:
{ foo: bar, bar: { foo: bar, bar: baz } }
El segundo argumento del método dump() personaliza el nivel en el cual el resultado cambia de la representación ampliada a en línea:
echo $dumper->dump($array, 1);
foo: bar
bar: { foo: bar, bar: baz }
echo $dumper->dump($array, 2);
foo: bar
bar:
foo: bar
bar: baz
El sitio web de YAML dice que es «un estándar para la serialización de datos humanamente legibles para todos los lenguajes de programación».
Si bien el formato YAML puede describir complejas estructuras de datos anidadas, este capítulo sólo describe el conjunto mínimo de características necesarias para usar YAML como un formato de archivo de configuración.
YAML es un lenguaje simple que describe datos. Como PHP, que tiene una sintaxis para tipos simples, como cadenas, booleanos, números en punto flotante, o enteros. Pero a diferencia de PHP, este distingue entre arreglos (secuencias) y hashes (asignaciones).
La sintaxis para escalares es similar a la sintaxis de PHP.
Una cadena en YAML
'Una cadena entre comillas simples en YAML'
Truco
En una cadena entre comillas simples, una comilla simple ' debe ser doble:
'Una comilla simple '' en una cadena entre comillas simples'
"Una cadena entre comillas dobles en YAML\n"
Los estilos de citado son útiles cuando una cadena empieza o termina con uno o más espacios relevantes.
Truco
El estilo entre comillas dobles proporciona una manera de expresar cadenas arbitrarias, utilizando secuencias de escape \. Es muy útil cuando se necesita incrustar un \n o un carácter Unicode en una cadena.
Cuando una cadena contiene saltos de línea, puedes usar el estilo literal, indicado por la línea vertical (|), para indicar que la cadena abarcará varias líneas. En literales, se conservan los saltos de línea:
|
\/ /| |\/| |
/ / | | | |__
Alternativamente, puedes escribir cadenas con el estilo de plegado, denotado por >, en el cual cada salto de línea es sustituido por un espacio:
>
Esta es una oración muy larga
que se extiende por varias líneas en el YAML
pero que se reproduce como una cadena
sin retornos de carro.
Nota
Observa los dos espacios antes de cada línea en los ejemplos anteriores. Ellos no aparecen en las cadenas PHP resultantes.
# un entero
12
# un octal
014
# un hexadecimal
0xC
# un float
13.4
# un número exponencial
1.2e+34
# infinito
.inf
Los nulos en YAML se pueden expresar con null o ~.
Los booleanos en YAML se expresan con true y false.
YAML utiliza la norma ISO-8601 para expresar fechas:
2001-12-14t21:59:43.10-05:00
# fecha simple
2002-12-14
Rara vez se utiliza un archivo YAML para describir un simple escalar. La mayoría de las veces, describe una colección. Una colección puede ser una secuencia o una asignación de elementos. Ambas, secuencias y asignaciones se convierten en arreglos PHP.
Las secuencias usan un guión seguido por un espacio:
- PHP
- Perl
- Python
El archivo YAML anterior es equivalente al siguiente código PHP:
array('PHP', 'Perl', 'Python');
La asignación utiliza dos puntos seguidos por un espacio (: ) para marcar cada par clave/valor:
PHP: 5.2
MySQL: 5.1
Apache: 2.2.20
el cual es equivalente a este código PHP:
array('PHP' => 5.2, 'MySQL' => 5.1, 'Apache' => '2.2.20');
Nota
En una asignación, una clave puede ser cualquier escalar válido.
El número de espacios entre los dos puntos y el valor no importa:
PHP: 5.2
MySQL: 5.1
Apache: 2.2.20
YAML utiliza sangría con uno o más espacios para describir colecciones anidadas:
"symfony 1.0":
PHP: 5.0
Propel: 1.2
"symfony 1.2":
PHP: 5.2
Propel: 1.3
El YAML anterior es equivalente al siguiente código PHP:
array(
'symfony 1.0' => array(
'PHP' => 5.0,
'Propel' => 1.2,
),
'symfony 1.2' => array(
'PHP' => 5.2,
'Propel' => 1.3,
),
);
Hay una cosa importante que tienes que recordar cuando utilices sangría en un archivo YAML: La sangría se debe hacer con uno o más espacios, pero nunca con tabulaciones.
Puedes anidar secuencias y asignaciones a tu gusto:
'Chapter 1':
- Introduction
- Event Types
'Chapter 2':
- Introduction
- Helpers
YAML también puede utilizar estilos de flujo para colecciones, utilizando indicadores explícitos en lugar de sangría para denotar el alcance.
Puedes escribir una secuencia como una lista separada por comas entre corchetes ([]):
[PHP, Perl, Python]
Una asignación se puede escribir como una lista separada por comas de clave/valores dentro de llaves ({}):
{ PHP: 5.2, MySQL: 5.1, Apache: 2.2.20 }
Puedes mezclar y combinar estilos para conseguir mejor legibilidad:
'Chapter 1': [Introduction, Event Types]
'Chapter 2': [Introduction, Helpers]
"symfony 1.0": { PHP: 5.0, Propel: 1.2 }
"symfony 1.2": { PHP: 5.2, Propel: 1.3 }
En YAML puedes añadir comentarios anteponiendo una almohadilla (#):
# Comentario en una línea
"symfony 1.0": { PHP: 5.0, Propel: 1.2 } # Comentario al final de una línea
"symfony 1.2": { PHP: 5.2, Propel: 1.3 }
Nota
Los comentarios simplemente son ignorados por el analizador de YAML y no es necesario sangrarlos de acuerdo al nivel de anidamiento actual de una colección.
