Symfony 2: Primer proyecto

En este segundo capítulo del mini-curso de Symfony 2 explicaré como crear un proyecto Symfony 2 desde cero para entornos Linux. Por supuesto existe la posibilidad de utilizar Symfony 2 en Windows y en Mac OS X, pero yo voy a centrarme en Linux y concretamente en Ubuntu, que es lo que uso habitualmente. La instalación en Mac OS X probablemente sea similar a la de Linux y para Windows seguro que existen otros manuales.

Lo primero y más importante: Vamos a suponer que el usuario dispone de un PC con sistema operativo Linux y que ha instalado tanto el servidor web Apache como el lenguaje PHP. Symfony 2 requiere al menos la versión 5.3.3 de PHP y algunas extensiones específicas. Aquí puede consultar todos los requerimientos de Symfony 2.

Composer

Empezaremos por el principio: Instalando Composer.

Composer es una herramienta imprescindible para desarrollar aplicaciones y sitios web en Symfony 2. Los proyectos Symfony utilizan diversas librerías externas (llamadas dependencias) que a su vez puede que usen otras librerías y Composer es la herramienta que se encarga de mantener actualizadas esas dependencias. Por ejemplo cuando queremos cambiar la versión usada de una librería o del propio Symfony, Composer se encarga de comprobar la compatibilidad de las otras librerías del proyecto, descargando si es necesario las versiones compatibles o avisando de las posibles incompatibilidades. A la hora de crear un proyecto Symfony 2, Composer comprueba la lista de dependencias del proyecto, decide qué librerías hay que instalar, qué versiones concretas se instalan y el orden correcto de instalación. Es una herramienta muy potente.

Para instalar Composer globalmente hay que seguir los siguientes pasos:

1. Abre una terminal y escribe:

$ curl -s https://getcomposer.org/installer | php

2. Aparecerá un nuevo archivo llamado composer.phar. Para comprobar que se ha instalado correctamente, ejecuta el siguiente comando que muestra el menú de opciones de Composer:

$ php composer.phar

3. Por último mueve el archivo composer.phar a un directorio de ejecutables del sistema:

$ sudo mv composer.phar /usr/local/bin/composer

4. Comprueba que todo funciona como es debido ejecutando el comando composer sin opciones desde cualquier directorio.

Con esto habremos instalado Composer de forma global en el ordenador. De esta forma para actualizar la versión de Composer de todos los proyectos bastará con ejecutar el siguiente comando desde un terminal:

$ sudo composer self-update

Creando un proyecto base

Una vez hemos instalado Composer, podemos usarlo para crear un proyecto Symfony 2 básico:

$ composer create-project symfony/framework-standard-edition
<carpeta> <version>

En este caso <carpeta> es el directorio raíz del proyecto (por ejemplo "/var/www/vhosts/masquecursos/") y <version> es la versión de Symfony 2 a instalar. En el momento de escribir estas líneas la última versión estable de Symfony es la 2.3.5 y otras versiones disponibles serían la anterior 2.2.8 y la siguiente 2.4.0-BETA1. Más información en la página de instalación de Symfony.

El programa de instalación pedirá algunos datos necesarios para la misma:

• Driver de base de datos: Generalmente será MySQL (pdo_mysql), pero podría ser SQLite (pdo_sqlite), PostgreSQL (pdo_pgsql), Microsoft SQL Server (pdo_sqlsrv), Oracle-PDO (pdo_oci), Oracle-No PDO (oci8), etc.
• Host de base de datos: Por defecto 127.0.0.1.
• Puerto de base de datos: Por defecto null.
• Nombre de base de datos: Depende del proyecto.
• Nombre del usuario de base de datos: Depende del proyecto.
• Clave de acceso del usuario de base de datos: Depende del proyecto.
• Protocolo de transporte para envío de emails: Por defecto smtp.
• Host para envío de emails: Por defecto 127.0.0.1.
• Nombre del usuario para envío de emails: Depende del proyecto.
• Clave de acceso del usuario para envío de emails: Depende del proyecto.
• Identificador local (locale): Por defecto en.
• Clave secreta: Para configurar el sistema de seguridad.

Se pueden dejar los valores por defecto pues más adelante podremos cambiarlos. El programa de instalación creará la estructura básica de directorios de un proyecto Symfony 2 que es la siguiente:

• proyecto/
  • composer.json
  • composer.lock
  • app/
    • check.php
    • console
    • cache/
    • config/
    • logs/
  • bin/
  • src/
  • vendor/
  • web/
    • app.php
    • app_dev.php
    • config.php

Cada una de las subcarpetas contiene a su vez otros archivos y carpetas, pero los que aparecen aquí son los más importantes. Más adelante hablaremos de lo que hay en cada carpeta y para que sirve cada archivo. Por ahora basta con saber que Composer nos crea todo esta estructura de carpetas y archivos.

Comprobaciones post-instalación

Todo proyecto Symfony 2 viene con un programa que permite comprobar si el ordenador cumple todos los requerimientos necesarios para el correcto funcionamiento del framework. Para ejecutarlo basta con abrir el terminal, entrar en el directorio del proyecto y teclear:

$ php app/check.php

Al ejecutar dicha utilidad, obtendremos una lista de requerimientos indicando en cada caso si tenemos la instalación correcta (OK) o si hay algún error (ERROR) o aviso (WARNING). Los errores (mandatory requirements) es necesario corregirlos antes de nada porque sino probablemente el proyecto no funcionará. Los avisos (optional checks) es conveniente corregirlos, pero no obligatorio.

Una vez comprobado que todos los requisitos están soportados por nuestra instalación se debe ejecutar otra utilidad llamada console.

$ app/console

Si todo es correcto se nos mostrará una lista de opciones de la consola Symfony. Más adelante veremos que esta consola es muy útil y se usa mucho para acciones comunes: limpiar la cache, crear la base de datos, crear entidades Doctrine, crear bundles, etc.

El problema de los permisos

Symfony 2 necesita permisos de escritura sobre dos carpetas del proyecto app/cache/ y app/logs/. Todas las demás carpetas pueden ser de sólo lectura, pero esas dos no. El problema es que el usuario Linux de la consola no es el mismo que el del navegador web (Apache) y ambos necesitan acceso a esos directorios, lo que puede provocar diversos problemas tipo "RuntimeException: Could not create cache directory" y otros similares. Para solucionarlo basta dar permisos de escritura a todos los usuarios para esos dos directorios concretos:

$ sudo chmod -R 777 app/cache/ app/logs/

Siendo puristas habría que dar permisos de escritura sólo al usuario www-data (Apache) o arreglar el tema de permisos vía grupo de trabajo que son las opciones recomendadas para entornos de producción, pero para el entorno de desarrollo sirve el chmod 777. Aquí puedes encontrar más información sobre cómo solucionar el problema de los permisos de Symfony 2.

Configurando el entorno

Para que el entorno de desarrollo sea lo más parecido posible al entorno de producción y aprovechando las características del servidor web Apache, vamos a crear un virtual host para este proyecto. Para ello en Ubuntu crearemos un archivo en la carpeta /etc/apache2/sites-available/ (ojo se necesitan permisos de root) y lo llamaremos como el proyecto (por ejemplo masquecursos). El contenido será el siguiente:

<VirtualHost *:80>
  ServerName masquecursos.me
  ServerAdmin webmaster@masquecursos.me
  DocumentRoot /var/www/vhosts/masquecursos/web
  DirectoryIndex app.php
  <Directory /var/www/vhosts/masquecursos/web>
    AllowOverride All
    Allow from All
  </Directory>
</VirtualHost>

Cada distribución de Linux es distinta y dicho archivo puede ser necesario crearlo en otra carpeta, aunque el contenido será el mismo. En Ubuntu posteriormente a la creación del archivo en /etc/apache2/sites-available/ es necesario crear un enlace simbólico en /etc/apache2/sites-enabled/. También habrá que editar el archivo /etc/hosts y asociar el nombre del virtual host con la IP 127.0.0.1. Posteriormente será necesario reiniciar el servidor Apache. La secuencia completa sería la siguiente:

$ sudo gedit /etc/apache2/sites-available/masquecursos
$ cd /etc/apache2/sites-enabled/
$ ln -s /etc/apache2/sites-available/masquecursos
$ sudo gedit /etc/hosts
$ sudo service apache2 restart

Con esto habremos configurado el entorno de ejecución y podremos acceder a nuestro sitio web desde http://masquecursos.me/, pero no lo pruebes todavía pues aun no funcionará. Por ahora para ver el contenido del proyecto es necesario usar el controlador de desarrollo http://masquecursos.me/app_dev.php. Más adelante veremos que es eso y porque aun no funciona con el controlador frontal app.php.

Configuraciones finales

Si entramos en nuestro navegador preferido y escribimos http://masquecursos.me/config.php veremos una página web con una bienvenida de Symfony. En caso de que la instalación no cumpla los requerimientos técnicos se mostrará una pantalla de error con la misma información que nos daba el archivo app/check.php. A estas alturas esos errores ya deberían estar corregidos. Desde la pantalla de bienvenida podemos acceder a otra de configuración del entorno desde la que se pueden configurar los mismos parámetros que cuando creamos el proyecto con Composer. En cualquier caso esos parámetros de configuración del entorno están en el archivo app/config/parameters.yml por lo que pueden modificarse a mano de forma sencilla.

¡Y ya está! Ya hemos creado un primer proyecto Symfony 2 vacío. En el siguiente capítulo veremos como crear el primer bundle y haremos el típico Hola Mundo con Symfony.

Más información

• Installing and Configuring Symfony [EN]
• Requeriments for Running symfony 2 [EN]
• Instalando una distribución de Symfony 2 [ES]
• Instalando y configurando Symfony [ES]
• Cómo solucionar el problema de los permisos de Symfony 2 [ES]

Mini-curso de Symfony 2

• Primeros pasos: Conceptos y definiciones sobre Symfony 2.
• Primer proyecto: Como empezar un proyecto Symfony 2.