Symfony 1.0, la guía definitiva

5.2. Un vistazo general a los archivos de configuración

La configuración de las aplicaciones realizadas con Symfony se distribuye en varios archivos según su propósito. Los archivos contienen definiciones de parámetros, normalmente llamadas opciones de configuración. Algunos parámetros se pueden redefinir en varios niveles de la aplicación web (proyecto, aplicación y módulo) y otros parámetros son exclusivos de algún nivel. En los siguientes capítulos se muestran los diversos archivos de configuración relacionados con el tema de cada capítulo. En el Capítulo 19 se explica la configuración avanzada.

5.2.1. Configuración del Proyecto

Symfony crea por defecto algunos archivos de configuración relacionados con el proyecto. El directorio miproyecto/config/ contiene los siguientes archivos:

  • config.php: se trata del primer archivo que se ejecuta con cada petición o comando. Contiene la ruta a los archivos del framework y se puede modificar para realizar una instalación personalizada. Se pueden añadir instrucciones define de PHP al final de este archivo para que esas constantes sean accesibles en cualquier aplicación del proyecto. El Capítulo 19 muestra el uso más avanzado de este archivo.
  • databases.yml: contiene la definición de los accesos a bases de datos y las opciones de conexión de cada acceso (servidor, nombre de usuario, contraseña, nombre de base de datos, etc.) El Capítulo 8 lo explica en detalle. Sus parámetros se pueden redefinir en el nivel de la aplicación.
  • properties.ini: contiene algunos parámetros que utiliza la herramienta de línea de comandos, como son el nombre del proyecto y las opciones para conectar con servidores remotos. El Capítulo 16 muestra las opciones de este archivo.
  • rsync_exclude.txt: indica los directorios que se excluyen durante la sincronización entre servidores. El Capítulo 16 también incluye una explicación de este archivo.
  • schema.yml y propel.ini: son los archivos de configuración que utiliza Propel para el acceso a los datos (recuerda que Propel es el sistema ORM que incorpora Symfony). Se utilizan para que las librerías de Propel puedan interactuar con las clases de Symfony y con los datos de la aplicación. schema.yml contiene la representación del modelo de datos relacional del proyecto. propel.ini se genera de forma automática y es muy probable que no necesites modificarlo. Si no se utiliza Propel, estos dos archivos son innecesarios. El Capítulo 8 explica en detalle el uso de estos dos archivos.

La mayoría de estos archivos los utilizan componentes externos o la línea de comandos e incluso algunos son procesados antes de que se inicie la herramienta que procesa archivos en formato YAML. Por este motivo, algunos de estos archivos no utilizan el formato YAML.

5.2.2. Configuración de la Aplicación

La configuración de la aplicación es la parte más importante de la configuración. La configuración se distribuye entre el controlador frontal (que se encuentra en el directorio web/) que contiene la definición de las constantes principales, el directorio config/ de la aplicación que contiene diversos archivos en formato YAML, los archivos de internacionalización se encuentran en el directorio i18n/ y también existen otros archivos del framework que contienen opciones de configuración ocultas pero útiles para la configuración de la aplicación.

5.2.2.1. Configuración del Controlador Frontal

La primera configuración de la aplicación se encuentra en su controlador frontal, que es el primer script que se ejecuta con cada petición. El listado 5-11 muestra el código por defecto del controlador frontal generado automáticamente:

Listado 5-11 - El controlador frontal de producción generado automáticamente

<?php

define('SF_ROOT_DIR',    realpath(dirname(__FILE__).'/..'));
define('SF_APP',         'miaplicacion');
define('SF_ENVIRONMENT', 'prod');
define('SF_DEBUG',       false);

require_once(SF_ROOT_DIR.DIRECTORY_SEPARATOR.'apps'.DIRECTORY_SEPARATOR.SF_APP.DIRECTORY_SEPARATOR.'config'.DIRECTORY_SEPARATOR.'config.php');

sfContext::getInstance()->getController()->dispatch();

Después de definir el nombre de la aplicación (miaplicacion) y el entorno en el que se ejecuta la aplicación (prod), se carga el archivo general de configuración y se despacha la petición dispatching). En este archivo se definen algunas constantes importantes:

  • SF_ROOT_DIR: directorio raíz del proyecto (en general no hay que modificar su valor, salvo que se cambie la estructura de archivos del proyecto).
  • SF_APP: el nombre de la aplicación. Es necesario para determinar las rutas de los archivos.
  • SF_ENVIRONMENT: nombre del entorno en el que se ejecuta la aplicación (prod, dev o cualquier otro valor que se haya definido). Se utiliza para determinar las opciones de configuración que se utilizan. Al final de este capítulo se explican los entornos de ejecución.
  • SF_DEBUG: activa el modo de depuración de la aplicación (el Capítulo 16 contiene los detalles).

Cuando se quiere cambiar alguno de estos valores, normalmente se crea un nuevo controlador frontal. El siguiente capítulo explica su funcionamiento y cómo crear nuevos controladores.

El Capítulo 19 explica en detalle cómo personalizar Symfony para que funcione con una estructura de directorios a medida.

5.2.2.2. Configuración principal de la Aplicación

La configuración más importante de la aplicación se encuentra en el directorio miproyecto/apps/miaplicacion/config/:

  • app.yml: contiene la configuración específica de la aplicación; por ejemplo se pueden almacenar variables globales que se utilizan en la lógica de negocio de la aplicación y que no se almacenan en una base de datos. Los ejemplos habituales de estas variables son los porcentajes de los impuestos como el IVA, los gastos de envío, direcciones de email de contacto, etc. Por defecto el archivo está vacío.
  • config.php: este archivo inicia la ejecucion de la aplicación, ya que realiza todas las inicializaciones necesarias para que la aplicación se pueda ejecutar. En este archivo se puede personalizar la estructura de directorios de la aplicación y se pueden añadir constantes que manejan las aplicaciones (el Capítulo 19 lo explica con más detalle). Comienza incluyendo el arhivo config.php del proyecto al que pertenece la aplicación.
  • factories.yml: Symfony incluye sus propias clases para el manejo de la vista, de las peticiones, de las respuestas, de la sesión, etc. No obstante, es posible definir otras clases propias para realizar estas tareas. El Capítulo 17 lo explica más detalladamente.
  • filters.yml: los filtros son trozos de código que se ejecutan con cada petición. En este archivo se definen los filtros que se van a procesar y cada módulo puede redefinir los filtros que se procesan. El Capítulo 6 explica en detalle los filtros.
  • logging.yml: permite definir el nivel de detalle con el que se generan los archivos de log, utilizados para el mantenimiento y la depuración de las aplicaciones. El Capítulo 16 explica más profundamente esta configuración.
  • routing.yml: almacena las reglas de enrutamiento, que permiten transformar las URL habituales de las aplicaciones web en URL limpias y sencillas de recordar. Cada vez que se crea una aplicación se crean unas cuantas reglas básicas por defecto. El Capítulo 9 está dedicado a los enlaces y el sistema de enrutamiento.
  • settings.yml: contiene las principales opciones de configuración de una aplicación Symfony. Entre otras, permite especificar si la aplicación utiliza la internacionalización, el idioma por defecto de la aplicación, el tiempo de expiración de las peticiones y si se activa o no la cache. Un cambio en una única línea de configuración de este archivo permite detener el acceso a la aplicación para realizar tareas de mantenimiento o para actualizar alguno de sus componentes. Las opciones más habituales y su uso se describen en el Capítulo 19.
  • view.yml: establece la estructura de la vista por defecto: el nombre del layout, el título de la página y las etiquetas <meta>; las hojas de estilos y los archivos JavaScript que se incluyen; el Content-Type por defecto, etc. También permite definir el valor por defecto de las etiquetas <title> y <meta>. El capítulo 7 explica detalladamente todas sus posibilidades. Cada módulo puede redefinir el valor de todas estas opciones.

5.2.2.3. Configuración de la Internacionalización

Las aplicaciones con soporte de internacionalización son las que pueden mostrar una misma página en diferentes idiomas. Para conseguirlo, es necesario realizar una configuración específica. Los dos sitios donde se configura la internacionalización en Symfony son:

  • Archivo i18n.yml del directorio config/ de la aplicación: en este archivo se establecen las opciones comunes de traducción de páginas, como por ejemplo el idioma por defecto, si las traducciones se guardan en archivos o bases de datos y su formato.
  • Los archivos de traducción en el directorio i18n/ de la aplicación: se trata de una especie de diccionarios que indican la traducción de cada frase que utilizan las plantillas de la aplicación de forma que cuando el usuario cambie de idioma sea posible mostrar las páginas en ese idioma.

Para activar el mecanismo de i18n, se debe modificar el archivo settings.yml. El Capítulo 13 profundiza en todas las características relacionadas con la i18n.

Nota Nota del traductor El término i18n es el más utilizado para referirse a la "internacionalización". Su origen proviene de las 18 letras que existen entre la letra "i" y la letra "n" en la palabra "internacionalización". Otras palabras siguen la misma técnica y así es habitual decir l10n para hablar de la "localization" o adaptación local de los contenidos.

5.2.2.4. Configuración adicional de la Aplicación

Algunos archivos de configuración se encuentran en el directorio de instalación de Symfony (en $sf_symfony_data_dir/config/) y por tanto no aparecen en los directorios de configuración de las aplicaciones. Las opciones que se encuentran en esos archivos son opciones para las que raramente se modifica su valor o que son globales a todos los proyectos. De todas formas, si necesitas modificar alguna de estas opciones, crea un archivo vacío con el mismo nombre en el directorio miproyecto/apps/miaplicacion/config/ y redefine todas las opciones que quieras modificar. Las opciones definidas en una aplicación siempre tienen preferencia respecto a las opciones definidas por el framework. Los archivos de configuración que se encuentran en el directorio config/ de la instalación de Symfony son los siguientes:

  • autoload.yml: contiene las opciones relativas a la carga automática de clases. Esta opción permite utilizar clases propias sin necesidad de incluirlas previamente en el script que las utiliza, siempre que esas clases se encuentren en algunos directorios determinados. El Capítulo 19 lo describe en detalle.
  • constants.php: define la estructura de archivos y directorios por defecto. Para redefinir estos valores, se debe utilizar el archivo de configuración config.php de la aplicación, como se muestra en el Capítulo 19.
  • core_compile.yml y bootstrap_compile.yml: define la lista de clases que se incluyen al iniciar la aplicación (en bootstrap_compile.yml) y las que se incluyen al procesar una petición (en core_compile.yml). Todas estas clases se concatenan en un único archivo PHP optimizado en el que se eliminan los comentarios y que acelera mucho la ejecución de la aplicación (ya que se reduce el número de archivos que se acceden a uno solo desde los más de 40 archivos necesarios originalmente para cada petición). Esta característica es muy necesaria cuando no se utiliza ningún acelerador de PHP. El Capítulo 18 incluye diversas técnicas para optimizar el rendimiento de las aplicaciones.
  • config_handlers.yml: permite añadir o modificar los manejadores de archivos de configuración. El Capítulo 19 contiene todos los detalles.
  • php.yml: este archivo se utiliza para comprobar que las directivas del archivo de configuración de PHP php.ini tienen los valores adecuados y permite redefinirlas si hace falta. Los detalles se explican en el Capítulo 19.

5.2.3. Configuración de los Módulos

Inicialmente los módulos no tienen ninguna configuración propia. En cualquier caso, es posible modificar las opciones de la aplicación en cualquier módulo que así lo requiera. Algunos de los usos típicos son los de cambiar la descripción HTML en todas las acciones de un módulo o para incluir un archivo JavaScript específico. También se pueden añadir nuevos parámetros exclusivamente para un módulo concreto.

Como se puede suponer, los archivos de configuración de los módulos se encuentran en el directorio miproyecto/apps/miaplicacion/modules/mimodulo/config/. Los archivos disponibles son los siguientes:

  • generator.yml: se utiliza para los módulos generados automáticamente a partir de una tabla de la base de datos, es decir, para los módulos utilizados en el scaffolding y para las partes de administración creadas de forma automática. Contiene las opciones que definen como se muestran las filas y los registros en las páginas generadas y también define las interacciones con el usuario: filtros, ordenación, botones, etc. El Capítulo 14 explica todas estas características.
  • module.yml: contiene la configuración de la acción y otros parámetros específicos del módulo (es un archivo equivalente al archivo app.yml de la aplicación). El Capítulo 6 lo explica en detalle.
  • security.yml: permite restringir el acceso a determinadas acciones del módulo. En este archivo se configura que una página solamente pueda ser accedida por los usuarios registrados o por un grupo de usuarios registrados con permisos especiales. En el Capítulo 6 se detalla su funcionamiento.
  • view.yml: permite configurar las vistas de una o de todas las acciones del módulo. Redefine las opciones del archivo view.yml de la aplicación y su funcionamiento se describe en el Capítulo 7.
  • Archivos de validación de datos: aunque se encuentran en el directorio validate/ en vez del directorio config/, se trata de archivos de configuración creados con YAML y que se emplean para controlar los datos introducidos en los formularios. En el Capítulo 10 se estudian en detalle.

Casi todos los archivos de configuración de los módulos permiten definir parámetros para todas las vistas y/o acciones del módulo o solo para una serie de vistas y/o acciones.