Ver índice de contenidos del libro

19.1. Opciones de Symfony

El archivo miaplicacion/config/settings.yml contiene la configuración principal de Symfony para la aplicación llamada miaplicacion. 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

Cuando una regla de enrutamiento no define el parámetro module o el parámetro action, se utilizan los valores del archivo settings.yml:

  • default_module: parámetro module por defecto. Su valor por defecto es default.
  • default_action: parámetro action por defecto. Su valor por defecto es index.

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 $sf_symfony_data_dir/modules/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.
  • unavailable_module y unavailable_action: acción que se ejecuta cuando un usuario solicita una página en una aplicación que ha sido deshabilitada. Su valor por defecto es default/unavailable. Para deshabilitar una aplicación entera, se establece la opción available a off en el archivo settings.yml.

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.

Página por defecto para el error 404

Figura 19.1 Página por defecto para el error 404

Se pueden modificar las páginas por defecto de 2 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, disabled y unavailable) y todas las plantillas relacionadas (indexSuccess.php, error404Success.php, loginSuccess.php, secureSuccess.php, disabledSuccess.php y unavailableSuccess.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 2 páginas se encuentran en el directorio $sf_symfony_data_dir/web/errors/:

  • error500.php: página que se muestra cuando ocurre un error en el entorno de producción. En otros entornos en los que la opción SF_DEBUG está puesta a true, 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 se está borrando la cache (es decir, durante el tiempo que transcurre entre la ejecución de la tarea symfony clear-cache 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 error500.php y unavailable.php en el directorio web/errors/ de la aplicación. Si están disponibles en ese directorio, Symfony las utiliza en vez de sus propias páginas.

Nota Para redireccionar las peticiones a la página unavailable.php cuando se necesite, se debe establecer la opción check_lock a on en el archivo settings.yml de la aplicación. Esta opción está desactivada por defecto porque reduce muy ligeramente el rendimiento para cada petición.

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

Opción Descripción Valor por defecto
use_database Activa el gestor de bases de datos. Se debe establecer a off si no se utilizan bases de datos on
use_security Activa las características de seguridad (acciones seguras y credenciales, como se vio en el capítulo 6). El filtro de seguridad por defecto (sfBasicSecurityFilter) solo se activa si esta opción vale on on
use_flash Activa el uso de parámetros flash (ver capítulo 6). Si nunca se utiliza el método set_flash() en las acciones, se puede establecer su valor a off. El filtro de parámetros flash (sfFlashFilter) solamente se activa si esta opción vale on on
i18n Activa la traducción de la interfaz de la aplicación (ver capítulo 13). En las aplicaciones multiidioma debería establecerse su valor a on off
logging_enabled Activa el sistema de log de eventos de Symfony. Si se establece su valor a off, no se tienen en cuenta las opciones del archivo logging.yml y se desactiva por completo el uso de archivos de log en Symfony on
escaping_strategy Activa y establece la política utilizada por el mecanismo de escape (ver capítulo 7). Si no se utiliza el contenedor $sf_data en las plantillas, se puede establecer su valor a off bc
cache Activa el mecanismo de cache para las plantillas (ver capítulo 12). Si algún módulo define un archivo cache.yml, su valor debe ser on. El filtro de la cache (sfCacheFilter) solamente se activa si esta opción vale on off en desarrollo, on en producción
web_debug Activa la barra de depuración web para depurar fácilmente las aplicaciones (ver capítulo 16). Para mostrar la barra en todas las páginas, se establece su valor a on. El filtro de depuración web (sfWebDebugFilter) solamente se activa si esta opción vale on on en desarrollo, off en producción
check_symfony_version Activa la comprobación de la versión de Symfony para cada petición. Si se quiere borrar la cache automáticamente después de actualizar el framework, su valor debe ser on. Si se borra manualmente la cache después de cada actualización, su valor debe ser off off
check_lock Activa el sistema de bloqueo de la aplicación, que se inicia mediante las tareas clear-cache y disable (ver sección anterior). Si se estable su valor a on, todas las peticiones a una aplicación deshabilitada se redirigen a la página $sf_symfony_data_dir/web/errors/unavailable.php off
compressed Activa la compresión de la respuesta mediante PHP. Si se establece a on, se comprime el código HTML generado antes de enviar la respuesta mediante las opciones de compresión de PHP off
use_process_cache Activa las optimizaciones de Symfony mediante los aceleradores de PHP. Cuando se isntala algún acelerador (como por ejemplo APC, XCache o eAccelerator), Symfony los utiliza para mantener sus propios objetos y configuración en memoria durante las distintas peticiones. Se puede establecer su valor a off durante el desarrollo de la aplicación o cuando no se quieren utilizar los aceleradores de PHP. Aunque no se disponga de ningún acelerador instalado, se puede establecer su valor a on sin que se penalice el rendimiento de la aplicación on

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 bc, both, on o off.
  • La opción escaping_method puede valer ESC_RAW, ESC_ENTITIES, ESC_JS o ESC_JS_NO_ENTITIES.

19.1.3.2. Opciones del sistema de enrutamiento

El archivo settings.yml permite establecer dos opciones del sistema de enrutamiento (ver capítulo 9):

  • 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.
  • 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 2 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).

19.1.3.5. Opciones para los archivos de log

El archivo settings.yml incluye 2 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 341 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 4095 para el entorno de desarrollo (los eventos que se guardan en el log son E_ALL y E_STRICT).
  • La opción web_debug activa la barra de depuración web. su valor debería ser on 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 JavaScript del editor de textos avanzado se configuran mediante la opción rich_text_js_dir (por defecto, js/tiny_mce)
  • Las librerías de Prototype se configuran mediante prototype_web_dir (por defecto, /sf/prototype)
  • Los archivos del generador de administraciones se configuran mediante admin_web_dir
  • Los archivos de la barra de depuración web se configuran mediante web_debug_web_dir
  • Los archivos JavaScript del calendario avanzado se configuran mediante calendar_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, Cache y Form. 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.

19.1.3.10. Otras configuraciones

El archivo settings.yml contiene otras opciones que Symfony utiliza internamente para definir su comportamiento. El listado 19-1 muestra todas las opciones en el mismo orden en el que aparecen en el archivo de configuración.

Listado 19-1 - Otras opciones de configuración, en miaplicacion/config/settings.yml

# Eliminar los comentarios de las clases internas de Symfony, tal y como se define
# en el archivo core_compile.yml
strip_comments:         on
# Funciones que se ejecutan cuando una clase se solicita y no está cargada
# Se indica en forma de array de elementos ejecutables. Lo utilizan los
#  puentes o enlaces de Symfony
autoloading_functions:  ~
# Tiempo de caducidad de una sesión, en segundos
timeout:                1800
# Máximo número de forwards que se realizan antes de lanzar una excepción
max_forwards:           5
# Constantes globales
path_info_array:        SERVER
path_info_key:          PATH_INFO
url_format:             PATH