19.1. Opciones de Symfony

El archivo frontend/config/settings.yml contiene la configuración principal de Symfony para la aplicación llamada frontend. Aunque ya se ha visto la utilidad de varias de sus opciones en los capítulos anteriores, a continuación se repasan todas estas opciones.

Como se explicó en el capítulo 5, este archivo es dependiente del entorno, lo que significa que cada opción puede tomar un valor diferente en cada entorno de ejecución. Todas las opciones definidas en este archivo son accesibles desde el código de PHP mediante la clase sfConfig. El nombre del parámetro que se debe utilizar está formado por el nombre de la opción y el prefijo sf_. Si se quiere obtener el valor de la opción cache, se utiliza el parámetro sf_cache y se obtiene su valor mediante sfConfig::get('sf_cache').

19.1.1. Acciones y módulos por defecto

Symfony proporciona páginas por defecto para varias situaciones. Si se produce un error en el enrutamiento, Symfony ejecuta una acción del módulo default que se encuentra en el directorio sfConfig::get('sf_symfony_lib_dir')/controller/default/. El archivo settings.yml define la acción que se ejecuta en función del error producido:

• error_404_module y error_404_action: acción que se ejecuta cuando la URL solicitada por el usuario no cumple con ninguna de las rutas establecidas, o cuando se produce una excepción de tipo sfError404Exception. Su valor por defecto es default/error404.
• login_module y login_action: acción que se ejecuta cuando un usuario que no se ha autenticado intenta acceder a una página definida como segura (opción secure) en el archivo security.yml (el Capítulo 6 muestra los detalles). Su valor por defecto es default/login.
• secure_module y secure_action: acción que se ejecuta cuando un usuario no dispone de las credenciales requeriadas para una ejecutar una acción. Su valor por defecto es default/secure.
• module_disabled_module y module_disabled_action: acción que se ejecuta cuando un usuario solicita un módulo que sido deshabilitado mediante el archivo module.yml. Su valor por defecto es default/disabled.

Antes de instalar una aplicación en producción, se deberían personalizar todas esas acciones, ya que las plantillas del módulo default incluyen el logotipo de Symfony en todas las páginas. La figura 19-1 muestra el aspecto de una de estas páginas, la página del error 404.

Figura 19.1 Página por defecto para el error 404

Se pueden modificar las páginas por defecto de dos formas:

• Se puede crear un módulo llamado default dentro del directorio modules/ de la aplicación y redefinir todas las acciones definidas en el archivo settings.yml (index, error404, login, secure y disabled) y todas las plantillas relacionadas (indexSuccess.php, error404Success.php, loginSuccess.php, secureSuccess.php y disabledSuccess.php).
• Se pueden modificar las opciones del módulo y acción por defecto del archivo settings.yml para utilizar páginas de la propia aplicación.

Existen otras dos páginas que muestran el mismo aspecto que el resto de páginas de Symfony y que también se deben modificar antes de instalar la aplicación en producción. Estas páginas no se encuentran en el módulo default, ya que se muestran cuando Symfony no se ejecuta correctamente. Estas dos páginas se encuentran en el directorio sfConfig::get('sf_symfony_lib_dir')/exception/data/:

• error.html.php: página que se muestra cuando ocurre un error en el entorno de producción. En otros entornos en los que la depuración de aplicaciones está activada, Symfony muestra en estos casos un mensaje de error explícito y la traza completa de la ejecución (ver los detalles en el capítulo 16).
• unavailable.php: página que se muestra cuando un usuario solicita una página mientras la aplicación está deshabilitada (con la tarea project:disable). También se muestra esta página mientras se está borrando la cache (es decir, durante el tiempo que transcurre entre la ejecución de la tarea php symfony cache:clear y la finalización de esta tarea). Los sistemas que disponen de una cache muy grande, pueden tardar varios segundos en borrarla entera. Como Symfony no puede ejecutar una petición con una cache a medio borrar, las peticiones que se reciben antes del borrado completo se redirigen a esta página.

Para personalizar el aspecto de estas páginas, se crean los archivos error.html.php y unavailable.php en el directorio config/ del proyecto o de la aplicación. Si están disponibles en ese directorio, Symfony las utiliza en vez de sus propias páginas.

19.1.2. Activando características opcionales

Algunas de las opciones del archivo settings.yml controlan las características opcionales del framework que se pueden activar y desactivar. Como desactivar las opciones que no se utilizan mejora el rendimiento de las aplicaciones, es conveniente repasar las opciones de la tabla 19-1 antes de instalar la aplicación en producción.

Tabla 19-1 - Características opcionales que se pueden activar mediante settings.yml

19.1.3. Configuración de cada característica

Symfony utiliza algunas opciones del archivo settings.yml para modificar el comportamiento de algunas de sus características, como la validación de formularios, la cache, los módulos externos, etc.

19.1.3.1. Opciones del mecanismo de escape

Las opciones del mecanismo de escape controlan la forma en la que las plantillas acceden a las variables (ver capítulo 7). El archivo settings.yml incluye dos opciones para esta característica:

• La opción escaping_strategy puede tomar los valores true o false.
• La opción escaping_method puede valer ESC_RAW, ESC_SPECIALCHARS, ESC_ENTITIES, ESC_JS o ESC_JS_NO_ENTITIES.

19.1.3.2. Opciones del sistema de enrutamiento

Las opciones del sistema de enrutamiento (ver capítulo 9) se definen en el archivo de configuración factories.yml, bajo la clave routing. El listado 19-1 muestra la configuración por defecto del sistema de enrutamiento.

Listado 19-1 - Opciones de configuración del sistema de enrutamiento, en frontend/config/factories.yml

routing:
  class: sfPatternRouting
  param:
    load_configuration: true
    suffix:             .
    default_module:     default
    default_action:     index
    variable_prefixes:  [':']
    segment_separators: ['/', '.']
    variable_regex:     '[\w\d_]+'
    debug:              %SF_DEBUG%
    logging:            %SF_LOGGING_ENABLED%
    cache:
      class: sfFileCache
      param:
        automatic_cleaning_factor: 0
        cache_dir:                 %SF_CONFIG_CACHE_DIR%/routing
        lifetime:                  31556926
        prefix:                    %SF_APP_DIR%

• La opción suffix establece el sufijo por defecto para las URL generadas. Su valor por defecto es un punto (.), lo que significa que no se añade ningún sufijo. Si se establece su valor a .html, todas las URL generadas parecerán páginas estáticas.
• Cuando una regla de enrutamiento no define los parámetros module o action, se utilizan los valores por defecto de factories.yml:
  • default_module: valor por defecto del parámetro module. Su valor por defecto es default.
  • default_action: valor por defecto del parámetro action. Su valor por defecto es index.
• Los patrones de las rutas identifican los comodines con nombre mediante un prefijo formado por dos puntos (:). Se puede modificar ese valor por defecto para utilizar un formato más parecido a PHP. Para ello, se añade el símbolo del dólar ($) en el array de la opción variable_prefixes. De esta forma, se pueden utilizar patrones como /articulo/$ano/$mes/$dia/$titulo en vez de /articulo/:ano/:mes/:dia/:titulo
• Los patrones de cada regla separan los diferentes comodines con nombre mediante los separadores. Por defecto, los separadores permitidos son la barra (/) y el punto (.). Se pueden añadir todos los separadores que se necesiten en la opción segment_separators. Si por ejemplo se añade el guión medio (-), se pueden crear patrones como /articulo/:ano-:mes-:dia/:titulo
• En el entorno de producción, el sistema de enrutamiento utiliza una cache para mejorar el rendimiento en la transformación de URI internas en URL externas. Por defecto esta cache utiliza el sistema de archivos, pero se puede utilizar cualquier clase de cache, siempre que se declare esa clase y sus opciones en la opción cache. El capítulo 15 describe la lista completa de clases de cache. Para desactivar la cache del sistema de enrutamiento en el entorno de producción, se establece el valor true en la opción debug.

Las opciones anteriores son todas las opciones disponibles para la clase sfPatternRouting. Además, es posible utilizar otra clase para el sistema de enrutamiento de la aplicación, ya sea una clase propia o una de las factorías incluidas por Symfony (sfNoRouting y sfPathInfoRouting). Estas dos factorías hacen que las URL tengan el aspecto modulo/accion?clave1=valor1. La desventaja es que no se pueden personalizar, pero su gran ventaja es que son muy rápidas. La diferencia entre las dos es que la primera utiliza el GET de PHP y la segunda utiliza el PATH_INFO. Se pueden utilizar sobre todo en las interfaces de administración de las aplicaciones.

Existe una última opción relacionada con el sistema de enrutamiento, pero se define en el archivo settings.yml:

• La opción no_script_name activa o desactiva la aparición del nombre del controlador frontal en las URL generadas. La opción no_script_name solamente se puede activar para una sola aplicación dentro de un mismo proyecto, a no ser que se guarden los controladores frontales en varios directorios diferentes y se modifiquen las reglas de enrutamiento por defecto para las URL. En el entorno de producción, esta opción suele establecerse a on y suele vale off en el resto de entornos.

19.1.3.3. Opciones para la validación de formularios

Las opciones de validación de formularios controlan la forma en la que se muestran los mensajes de error de los helpers del grupo Validation (ver capítulo 10). Este tipo de errores se muestran dentro de etiquetas <div>, y utilizan el valor de la opción validation_error_class como atributo class del <div> y el valor de la opción validation_error_id_prefix para construir el atributo id. Los valores por defecto son form_error y error_for_, por lo que los atributos generados por la llamada al helper form_error() para un campo de formulario llamado campo serían class="form_error" id="error_for_campo".

Otras dos opciones determinan los caracteres que se muestran delante y detrás de los mensajes de error: validation_error_prefix y validation_error_suffix. Cambiando su valor, se modifica el aspecto de todos los mensajes de error generados.

19.1.3.4. Opciones para la cache

Las mayoría de opciones de la cache se definen en el archivo cache.yml, salvo dos opciones incluidas en el archivo settings.yml: cache que activa el mecanismo de cache de las plantillas y etag que controla la etiqueta Etag en el lado del servidor (ver capítulo 15). También es posible configurar en el archivo factories.yml el tipo de almacenamiento que se utiliza en todas las caches (la cache de la vista, la del sistema de enrutamiento y la de la internacionalización). El listado 19-2 muestra la configuración por defecto de la factoría de la cache de la vista.

Listado 19-2 - Opciones de configuración de la cache de la vista, en frontend/config/factories.yml

view_cache:
  class: sfFileCache
  param:
    automatic_cleaning_factor: 0
    cache_dir:                 %SF_TEMPLATE_CACHE_DIR%
    lifetime:                  86400
    prefix:                    %SF_APP_DIR%/template

La opción class puede tomar los valores sfFileCache, sfAPCCache, sfEAcceleratorCache, sfXCacheCache, sfMemcacheCache y sfSQLiteCache. También puedes utilizar tu propia clase, siempre que herede de la clase sfCache y proporcione los mismos métodos genéricos para guardar, obtener y borrar elementos en la cache mediante claves. Las opciones de esta factoría dependen de cada clase, aunque algunas opciones son comunes para todas:

• lifetime establece el tiempo de expiración en segundos de los elementos de la cache.
• prefix establece el prefijo que se añade a cada clave de la cache (utiliza el nombre del entorno de ejecución en el prefijo para que la aplicación utilice una cache diferente en cada entorno donde se ejecute). Para compartir una misma cache entre dos aplicaciones, es necesario utilizar el mismo prefijo.

Además, para cada factoría es necesario definir el lugar en el que se va a almacenar la cache:

• sfFileCache utiliza el parámetro cache_dir para establecer la ruta absoluta hasta el directorio de la cache.
• sfAPCCache, sfEAcceleratorCache y sfXCacheCache no necesitan una opción para indicar el lugar en el que se almacena la cache, ya que utilizan las funciones nativas de PHP para comunicarse con los sistemas de cache de APC, EAccelerator y XCache respectivamente.
• sfMemcacheCache utiliza el parámetro host para establecer el hostname del servidor de Memcached. También se puede utilizar el parámetro servers para indicar un array de servidores.
• sfSQLiteCache utiliza el parámetro database para indicar la ruta absoluta hasta el archivo de la base de datos de tipo SQLite.

La documentación de la API de cada clase de cache contiene más información sobre todas sus opciones.

La vista no es el único componente que puede utilizar una cache. Las factorías routing y I18N incluyen un parámetro llamado cache en el que se puede indicar cualquier factoría de cache, de la misma forma que en la cache de la vista. El listado 19-1 por ejemplo muestra cómo el sistema de enrutamiento utiliza por defecto la cache para mejorar su rendimiento, pero se puede modificar esa opción por cualquier otro valor de los mostrados anteriormente.

19.1.3.5. Opciones para los archivos de log

El archivo settings.yml incluye dos opciones relacionadas con los archivos de log (ver capítulo 16):

• error_reporting especifica los eventos que se guardan en los archivos de log de PHP. Su valor por defecto es E_PARSE | E_COMPILE_ERROR | E_ERROR | E_CORE_ERROR | E_USER_ERROR para el entorno de producción (por lo que los eventos que se guardan en el log son E_PARSE, E_COMPILE_ERROR, E_ERROR, E_CORE_ERROR y E_USER_ERROR) y E_ALL | E_STRICT para el entorno de desarrollo.
• La opción web_debug activa la barra de depuración web. su valor debería ser true solamente en los entornos de desarrollo y pruebas.

19.1.3.6. Opciones para las rutas a los archivos estáticos

El archivo settings.yml también permite indicar la ruta a los archivos estáticos, también llamados "assets". Si se quiere utilizar una versión específica de un componente que es diferente a la que se incluye en Symfony, estas opciones permiten establecer la ruta a la nueva versión:

• Los archivos del generador de administración se configuran mediante admin_web_dir
• Los archivos de la barra de depuración web se configuran mediante web_debug_web_dir

19.1.3.7. Helpers por defecto

Los helpers por defecto se cargan en todas las plantillas y se configuran mediante la opción standard_helpers (ver capítulo 7). Por defecto, se incluyen los grupos de helpers Partial y Cache. Si algún grupo de helpers se utiliza en todas las plantillas, es mejor añadirlo a la opción standard_helpers para evitar tener que declarar su uso en todas las plantillas mediante use_helper().

19.1.3.8. Módulos activos

La opción enbled_modules establece los módulos de los plugins o del propio núcleo de Symfony que están activos. Aunque un plugin incluya un módulo, los usuarios no pueden acceder a este módulo a menos que haya sido incluido en la lista de la opción enabled_modules. Por defecto solamente se encuentra activado el módulo default de Symfony, que muestra las páginas por defecto de bienvenida, de errores como "página no encontrada", etc.

19.1.3.9. Juego de caracteres

El juego de caracteres utilizado en las respuestas es una opción global de la aplicación, ya que se utiliza en muchos componentes del framework (plantillas, mecanismo de escape, helpers, etc.). Su valor se define en la opción charset, cuyo valor por defecto y recomendado es utf-8.

all:
   tarjetascredito:
     falsa:            false    # app_tarjetascredito_falsa
     visa:             true     # app_tarjetascredito_visa
     americanexpress:  true     # app_tarjetascredito_americanexpress