5.1. El sistema de configuración (Symfony 1.1, la guía definitiva)

La mayoría de aplicaciones web comparten una serie de características, independientemente de su finalidad. Por ejemplo, es habitual restringir algunas partes de la aplicación a una serie de usuarios, utilizar un layout común para mostrar todas las páginas, los formularios deben volver a mostrar los datos que ha introducido el usuario después de una validación errónea. El framework define el comportamiento básico de estas características y el programador puede adaptar cada una mediante las opciones de configuración. Esta forma de trabajar ahorra mucho tiempo de desarrollo, ya que muchos cambios importantes no necesitan modificar ni siquiera una línea de código, aunque estos cambios impliquen muchos cambios internos. Además se trata de una forma mucho más eficiente, ya que permite asegurar que toda la configuración se encuentra en un lugar único y fácilmente localizable.

No obstante, este método también tiene dos inconvenientes muy importantes:

Los programadores acaban escribiendo archivos XML complejos y muy largos.
En una arquitectura basada en PHP, cada petición consumiría mucho más tiempo de proceso.

Considerando todas estas desventajas, Symfony utiliza solamente lo mejor de los archivos de configuración. De hecho, el objetivo del sistema de configuración de Symfony es ser:

Potente: todo lo que puede ser gestionado con archivos de configuración, se gestiona con archivos de configuración.
Simple: muchas de las características de la configuración no se utilizan habitualmente, por lo que las aplicaciones normales no tienen que tratar con ellas.
Sencillo: los archivos de configuración son sencillos de leer, de modificar y de crear por parte de los desarrolladores.
Personalizable: el lenguaje que se utiliza por defecto en los archivos de configuración es YAML, pero se puede cambiar por archivos INI, XML o cualquier otro formato que prefiera el programador.
Rápido: la aplicación nunca procesa los archivos de configuración, sino que se encarga de ello el sistema de configuración, que compila todos los archivos de configuración en trozos de código PHP que se pueden procesar muy rápidamente.

5.1.1. Sintaxis YAML y convenciones de Symfony

Symfony utiliza por defecto el formato YAML para la configuración, en vez de los tradicionales formatos INI y XML. El formato YAML indica su estructura mediante la tabulación y es muy rápido de escribir. El Capítulo 1 ya describe algunas de sus ventajas y las reglas más básicas. No obstante, se deben tener presentes algunas convenciones al escribir archivos YAML. En esta sección se mencionan las convenciones o normas más importantes. El sitio web de YAML (http://www.yaml.org/) contiene la lista completa de normas del formato.

En primer lugar, no se deben utilizar tabuladores en los archivos YAML, sino que siempre se deben utilizar espacios en blanco. Los sistemas que procesan YAML no son capaces de tratar con los tabuladores, por lo que la tabulación de los archivos se debe crear con espacios en blanco como se muestra en el listado 5-1 (en YAML un tabulador se indica mediante 2 espacios en blanco seguidos).

**Listado 5-1 - Los archivos YAML no permiten los tabuladores **

# No utilices tabuladores
all:
  -> mail:
  -> -> webmaster:  [email protected]

# Utiliza espacios en blanco
all:
  mail:
    webmaster: [email protected]

Si los parámetros son cadenas de texto que contienen espacios en blanco al principio o al final, se debe encerrar la cadena entera entre comillas simples. Si la cadena de texto contiene caracteres especiales, también se encierran con comillas simples, como se muestra en el listado 5-2.

Listado 5-2 - Las cadenas de texto especiales deben encerrarse entre comillas simples

error1: Este campo es obligatorio
error2: '  Este campo es obligatorio  '

# Las comillas simples que aparecen dentro de las cadenas de
# texto, se deben escribir dos veces
error3: 'Este `campo` es obligatorio'

Se pueden escribir cadenas de texto muy largas en varias líneas, además de juntar cadenas escritas en varias líneas. En este último caso, se debe utilizar un carácter especial para indicar que se van a escribir varias líneas (se puede utilizar > o |) y se debe añadir una pequeña tabulación (dos espacios en blanco) a cada línea del grupo de cadenas de texto. El listado 5-3 muestra este caso.

Listado 5-3 - Definir cadenas de texto muy largas y cadenas de texto multi-línea

# Las cadenas de texto muy largas se pueden escribir en
# varias líneas utilizando el carácter >
# Posteriormente, cada nueva línea se transforma en un
# espacio en blanco para formar la cadena de texto original.
# De esta forma, el archivo YAML es más fácil de leer
frase_para_recordar: >
  Vive como si fueras a morir mañana y
  aprende como si fueras a vivir para siempre.

# Si un texto está formado por varias líneas, se utiliza
# el carácter | para separar cada nueva línea. Los espacios
# en blanco utilizados para tabular las líneas no se tienen
# en cuenta.
direccion: |
  Mi calle, número X
  Nombre de mi ciudad
  CP XXXXX

Los arrays se definen mediante corchetes que encierran a los elementos o mediante la sintaxis expandida que utiliza guiones medios para cada elemento del array, como se muestra en el listado 5-4.

Listado 5-4 - Sintaxis de YAML para incluir arrays

# Sintaxis abreviada para los arrays
idiomas: [ Alemán, Francés, Inglés, Italiano ]

# Sintaxis expandida para los arrays
idiomas:
  - Alemán
  - Francés
  - Inglés
  - Italiano

Para definir arrays asociativos, se deben encerrar los elementos mediante llaves ({ y }) y siempre se debe insertar un espacio en blanco entre la clave y el valor de cada par clave: valor. También existe una sintaxis expandida que requiere indicar cada par clave: valor en una nueva línea y con una tabulación (es decir, con 2 espacios en blanco delante) como se muestra en el listado 5-5.

Listado 5-5 - Sintaxis de YAML para incluir arrays asociativos

# Sintaxis incorrecta, falta un espacio después de los 2 puntos
mail: {webmaster:[email protected],contacto:[email protected]}

# Sintaxis abreviada correcta para los array asociativos
mail: { webmaster: [email protected], contacto: [email protected] }

# Sintaxis expandida para los arrays asociativos
mail:
  webmaster: [email protected]
  contacto:  [email protected]

Para los parámetros booleanos, se pueden utilizar los valores on, 1 o true para los valores verdaderos y off, 0 o false para los valores falsos. El listado 5-6 muestra los posibles valores booleanos.

Listado 5-6 - Sintaxis de YAML para los valores booleanos

valores_verdaderos:   [ on, 1, true ]
valores_falsos:       [ off, 0, false ]

Es recomendable añadir comentarios (que se definen mediante el carácter #) y todos los espacios en blanco adicionales que hagan falta para hacer más fáciles de leer los archivos YAML, como se muestra en el listado 5-7.

Listado 5-7 - Comentarios en YAML y espacios adicionales para alinear valores

# Esta línea es un comentario
mail:
  webmaster: [email protected]
  contacto:  [email protected]
  admin:     [email protected]   # se añaden espacios en blanco para alinear los valores

En algunos archivos de configuración de Symfony, se ven líneas que empiezan por # (y por tanto se consideran comentarios y se ignoran) pero que parecen opciones de configuración correctas. Se trata de una de las convenciones de Symfony: la configuración por defecto, heredada de los archivos YAML del núcleo de Symfony, se repite en forma de líneas comentadas a lo largo de los archivos de configuracion de cada aplicación, con el único objetivo de informar al desarrollador. De esta forma, para modificar esa opción de configuración, solamente es necesario eliminar el carácter de los comentarios y establecer su nuevo valor. El listado 5-8 muestra un ejemplo.

Listado 5-8 - La configuración por defecto se muestra en forma de comentarios

# Por defecto la cache está desactivada
settings:
# cache: off

# Para modificar esta opción, se debe descomentar la línea
settings:
  cache: on

En ocasiones, Symfony agrupa varias opciones de configuración en categorías. Todas las opciones que pertenecen a una categoría se muestran tabuladas y bajo el nombre de esa categoría. La configuración es más sencilla de leer si se agrupan las listas largas de pares clave: valor. Los nombres de las categorías comienzan siempre con un punto (.) y el listado 5-19 muestra un ejemplo de uso de categorías.

Listado 5-9 - Los nombres de categorías son como los nombres de las clave, pero empiezan con un punto

all:
  .general:
    impuestos:  19.6

mail:
  webmaster:    [email protected]

En el ejemplo anterior, mail es una clave y general sólo es el nombre de la categoría. En realidad, el archivo YAML se procesa como si no existiera el nombre de la categoría, es decir, como se muestra en el listado 5-10. El parámetro impuestos realmente es descendiente directo de la clave all. No obstante, el uso de nombres de categorías facilita a Symfony el manejo de los arrays que se encuentran bajo la clave all.

Listado 5-10 - Los nombres de categorías solo se utilizan para hacer más fácil de leer los archivos YAML y la aplicación los ignora

all:
  impuestos:    19.6

mail:
  webmaster:    [email protected]

Si no te gusta YAML YAML solamente es una interfaz para definir las opciones que utiliza el código PHP, por lo que la configuración definida mediante YAML se transforma en código PHP. Si ya has accedido al menos una vez a la aplicación, comprueba la cache de su configuración (por ejemplo en cache/frontend/dev/config/). En ese directorio se encuentran los archivos PHP generados por la configuración YAML. Más adelante se detalla la cache de la configuración.

Lo mejor de todo es que si no quieres utilizar archivos YAML, puedes realizar la misma configuración a mano o mediante otros formatos (XML, INI, etc.) Más adelante en este libro se comentan otras formas alternativas a YAML para realizar la configuración e incluso se muestra como modificar las funciones de Symfony que se encargan de procesar la configuración (en el Capítulo 19). Utilizando estas técnicas, es posible evitar los archivos de configuración e incluso definir tu propio formato de configuración.

5.1.2. ¡Socorro, los archivos YAML han roto la aplicación!

Los archivos YAML se procesan y se transforman en array asociativos y arrays normales de PHP. Después, estos valores transformados son los que se utilizan en la aplicación para modificar el comportamiento de la vista, el modelo y el controlador. Por este motivo, cuando existe un error en un archivo YAML, normalmente no se detecta hasta que se utiliza ese valor específico. Para complicar las cosas, el error o la excepción que se muestra no siempre indica de forma clara que puede tratarse de un error en los archivos YAML de configuración.

Si la aplicación deja de funcionar después de un cambio en la configuración, se debe comprobar que no se ha cometido alguno de los errores típicos de los desarrolladores principiantes con YAML:

No existe un espacio en blanco entre la clave y su valor:

clave1:valor1      # Falta un espacio después del :

Alguna clave de una secuencia de valores está mal tabulada:

all:
  clave1:  valor1
   clave2: valor2  # Su tabulación no es igual que los otros miembros de la secuencia
  clave3:  valor3

Alguna clave o valor contiene caracteres reservados por YAML que no han sido encerrados por las comillas simples:

mensaje: dile lo siguiente: hola    # :, [, ], { y } están reservados por YAML
mensaje: 'dile lo siguiente: hola'  # Sintaxis correcta

La línea que se modifica está comentada:

# clave: valor     # No se tiene en cuenta porque empieza por #

Existen 2 claves iguales con diferentes valores dentro del mismo nivel:

clave1: valor1
clave2: valor2
clave1: valor3     # clave1 está definida 2 veces, solo se tiene en cuenta su último valor

Todos los valores se consideran cadenas de texto, salvo que se convierta de forma explícita su valor:

ingresos: 12,345   # El valor es una cadena de texto y no un número, salvo que se convierta