En el artículo anterior del Manual de Laravel ya explicamos cómo realizar la instalación de básica del framework PHP Laravel 5. Como has podido comprobar, instalar Laravel es muy fácil, pero en la mayoría de los casos habrá que completar algunas tareas básicas para dejarlo funcionando correctamente en nuestro sistema. En este artículo pretendemos ayudar explicando cuáles son esas posibles tareas, a la par que analizamos los problemas que te puedes encontrar durante la instalación.

Obviamente sería imposible recabar todos los tipos de problemas con los que te puedes encontrar cuando estés instalando Laravel 5, porque dependen de la configuración concreta del sistema donde lo vayamos a instalar. No obstante, vamos a hacer un listado de cosas que pueden fallar en este momento, en base a nuestra experiencia.

El temido enemigo en este caso es el mensaje "Whoops, looks like something went wrong.", que en la mayoría de los casos, en modo desarrollo, te debería advertir qué es lo que está funcionando mal. A partir de ese mensaje deberías encontrar la pista para saber como solucionar tu problema particular.

Ahora van algunas de las posibles causas y soluciones de problemas que hemos detectado.

Archivo de entorno inexistente

Hemos observado que si instalas Laravel 5 a partir del instalador (laravel new nombre_proyecto) no se crea el archivo de entorno. Ese es un archivo que está en la raíz del proyecto, que se llama ".env".

Fíjate que en la carpeta raíz debería haber un archivo llamado .env.example. Ese archivo es un ejemplo de configuración. La solución sería simplemente duplicar el archivo y llamarle ".env".

Atención aquí a la variable de entorno APP_DEBUG, que debería estar a "true" para que te de una descripción completa de los errores que se puedan producir al ejecutar Laravel. Si no está el archivo de la configuración del entorno, o dentro de él APP_DEBUG está a false, verás que el mensaje de error de Laravel no aparece con descripción detallada.

Como alternativa, via Composer también se puede acceder a la creación de este archivo de configuración del entorno. Si te fijas en el composer.json hay una sección de scripts que sirven para correr comandos post-instalación. Entre ellos hay uno que hace justamente la copia del .env.example al .env. El script se llama "post-root-package-install". Para ejecutarlo con Composer lanzamos el comando siguiente:

composer run-script post-root-package-install

Permisos de las carpetas

Otra situación que puede dar lugar a errores es que no tengas permisos de escritura en las carpetas que lo necesitan. Directorios dentro de "storage" y "bootstrap/cache" deben tener permisos de escritura para el servidor web. Si has instalado Laravel en una máquina Homestead no deberías preocuparte por este detalle, pero si lo estás haciendo en una máquina distinta quizás tengas que activarlos.

Como estamos en el ordenador de desarrollo podríamos simplemente asignar 777 a los permisos y así nos aseguramos que no nos de problemas este detalle.

chmod -R 777 storage

Este asunto está documentado en la documentación oficial, aunque no sugieren poner los permisos a un valor concreto. Nosotros sugerimos solo 777 porque es tu máquina local, nunca se debería hacer eso en el servidor remoto donde va a estar la aplicación en producción.

Llave de aplicación (Application Key)

En el caso de la instalación via el instalador de Laravel 5 también hemos observado que falta la llave de aplicación. En la documentación oficial menciona que esa llave debería haberse generado, tanto instalando con el instalador de Laravel (laravel new) como via Composer con la alternativa tradicional. Via composer sí se generó la llave, pero no via el instalador.

La solución es sencilla porque mediante el comando de Artisan key:generate se realiza todo el trabajo para ti.

Dentro de la raíz de tu proyecto, donde se encuentra el .env lanza el comando:

php artisan key:generate

Eso te debería lanzar algo como la siguiente salida:

Application key [dpGvjrnnKLGszdgcck1YSLrSMGeN61dy] set successfully.

Además el propio comando te actualiza el archivo .env, pero si no es así podrías hacerlo a mano tú mismo, en el epígrafe APP_KEY:

APP_KEY=dpGvjrnnKLGszdgcck1YSLrSMGeN61dy

Como nos avisan en la documentación, ten cuidado con este detalle porque si la llave de aplicación no ha sido generada los datos de las sesiones de usuario y otras informaciones encriptadas no estarán seguras.

Revisar config/app.php

En este archivo encontrarás información de configuración de la aplicación. Generalmente no necesitas tocarlo si estás impaciente y quieres ver ya el framework funcionando. Sin embargo encontrarás algunas cosas útiles como la variable "timezone" y "locale" que en una aplicación en producción desearás editar.

Otros elementos que se pueden configurar en otros archivos son Chache, Database, Session, que veremos más adelante.

URLs amigables a usuarios / buscadores

Laravel es capaz de mostrar las URL de aplicación de una manera amistosa para el usuario, y para los buscadores que puedan recorrer la página. Todo en Laravel comienza con un index.php que está dentro de la carpeta "public" (que debería ser tu document root). Para eliminar ese index.php de las URL y que éstas queden más limpias es posible que necesites tocar alguna cosa. Aunque si estás instalando via Homestead no deberías encontrarte con ningún problema en este sentido.

Laravel 5 viene con un archivo .htaccess que sirve para generar las URL amigables en Apache. Solo ten en cuenta que tu apache debe tener activado el mod_rewrite para que las redirecciones de .htaccess funcionen correctamente.

Además del .htaccess que encuentras en la carpeta "public" en la documentación de Laravel, en la sección de instalación http://laravel.com/docs/#installation y luego en la subsección "Pretty URL" te ofrecen una versión reducida del .htaccess que podrías probar si la que provee el framework no hace correctamente su trabajo.

Para los que están en Nginx se debe agregar una directiva en la configuración del sitio:

location / { try_files $uri $uri/ /index.php?$query_string; }

Esto es todo por el momento. Si queréis profundizar en el tema os recomendamos que os veáis los vídeos que encontraréis en el siguiente enlace: Primeros pasos con Laravel 5