Instalación y configuración de Laravel paso a paso

Hola, ¿cómo están? Continuando con el curso de Laravel, hoy instalamos el framework y creamos nuestro primer proyecto funcionando.

¡Empecemos!

Requisitos previos

Antes de instalar Laravel necesitas tres cosas en tu máquina:

• PHP en una versión reciente.
• Composer, el gestor de dependencias de PHP.
• Node.js y npm, para compilar los estilos y el JavaScript.

Si ya tienes XAMPP o Laragon instalado, PHP y Composer ya vienen incluidos. Comprueba las versiones:

php --version
composer --version
node --version

La forma recomendada: el instalador de Laravel

Laravel tiene un instalador propio que hace el proceso más cómodo. Se instala una sola vez:

composer global require laravel/installer

Y a partir de ahí, crear un proyecto es un comando:

laravel new sistema-clinica

El instalador te va a preguntar algunas cosas: si quieres un kit de inicio con autenticación, qué framework de pruebas prefieres y qué base de datos vas a usar. Para este curso, responde sin kit de inicio, Pest y MySQL.

Si prefieres no instalar el instalador

También funciona con Composer directamente:

composer create-project laravel/laravel sistema-clinica

Hace lo mismo, solo que sin las preguntas iniciales.

Si no tienes PHP instalado

Laravel ofrece un script que instala PHP, Composer y el instalador de una vez. En Windows, desde PowerShell como administrador:

Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://php.new/install/windows/8.5'))

Y en macOS o Linux:

/bin/bash -c "$(curl -fsSL https://php.new/install/mac/8.5)"

Después de ejecutarlo hay que reiniciar la terminal.

Levantar el proyecto

Entra a la carpeta y arranca:

cd sistema-clinica
npm install && npm run build
composer run dev

Ese composer run dev es la novedad que conviene conocer: levanta tres cosas a la vez —el servidor web, el procesador de colas y el compilador de assets—, así que no necesitas tres terminales abiertas.

Abre el navegador en:

http://localhost:8000

Si ves la pantalla de bienvenida de Laravel, ya está funcionando.

Con Laragon o XAMPP

Si prefieres usar tu entorno local en lugar del servidor incorporado, crea el proyecto dentro de la carpeta que sirve el servidor:

• Laragon: C:\laragon\www\
• XAMPP: C:\xampp\htdocs\

Con Laragon tendrás automáticamente sistema-clinica.test funcionando. Con XAMPP, el proyecto se abre en localhost/sistema-clinica/public, apuntando a la carpeta public, que es la única que debe ser accesible desde el navegador.

El archivo .env

Este archivo, en la raíz del proyecto, es donde vive toda la configuración que cambia entre tu computadora y el servidor de producción.

APP_NAME="Sistema Clínica"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8000

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=clinica
DB_USERNAME=root
DB_PASSWORD=

Tres cosas importantes sobre él:

No se sube al repositorio. Ya viene en el .gitignore, y por buenas razones: contiene contraseñas y claves. Es exactamente lo que advertimos en la lección de seguridad en PHP.

Hay un .env.example que sí se versiona, con las mismas variables pero sin valores. Es la plantilla para quien clone el proyecto.

APP_DEBUG=true solo en tu máquina. En producción va en false, porque con true cualquier error muestra el código fuente y las variables de entorno al visitante.

Para leer una variable desde el código:

$nombre = config('app.name');

Fíjate en que se usa config() y no env(). La razón la veremos al hablar de caché: env() deja de funcionar en producción cuando se cachea la configuración, y es un error clásico.

La clave de aplicación

El instalador la genera sola, pero si clonas un proyecto tendrás que crearla:

php artisan key:generate

Esa clave cifra las sesiones y las cookies. Sin ella, Laravel no arranca.

Configurar la base de datos

Crea la base en MySQL:

CREATE DATABASE clinica CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Ajusta las credenciales en el .env y comprueba que la conexión funciona:

php artisan migrate

Si las tablas se crean, la conexión está bien. Si da error, revisa que MySQL esté iniciado y que el nombre de la base coincida.

Lo veremos en detalle en la siguiente lección de configuración de base de datos.

Un detalle: si al crear el proyecto elegiste SQLite, Laravel crea un archivo database/database.sqlite y ya ejecuta las migraciones por ti. Es cómodo para probar, pero en este curso usaremos MySQL.

Configurar el editor

Con Visual Studio Code, estas extensiones cambian mucho la experiencia:

• Laravel VS Code Extension, la oficial. Autocompletado de rutas, vistas, traducciones y componentes.
• PHP Intelephense, para el análisis del código PHP.
• Laravel Blade Snippets, para las plantillas.

Además existe el Laravel LSP, que da soporte del framework a cualquier editor compatible:

composer global require laravel/lsp

Comprobar que todo está en orden

Un par de comandos útiles para verificar:

php artisan about

Muestra un resumen del entorno: versión de Laravel, de PHP, base de datos configurada, caché y colas. Es lo primero que ejecuto al llegar a un proyecto ajeno.

php artisan --version

Devuelve la versión del framework.

Problemas frecuentes

«laravel: command not found». El directorio global de Composer no está en el PATH. La ruta suele ser ~/.composer/vendor/bin o %USERPROFILE%\AppData\Roaming\Composer\vendor\bin.

Error de extensión faltante. Laravel necesita algunas extensiones de PHP. El mensaje dice cuál falta; se activa descomentando su línea en el php.ini.

Página en blanco o error 500. Mira storage/logs/laravel.log, que es donde Laravel registra todo. Casi siempre es un problema de permisos en storage o de falta de la clave de aplicación.

Permisos en Linux o macOS:

chmod -R 775 storage bootstrap/cache

«SQLSTATE[HY000] [1045] Access denied». Credenciales incorrectas en el .env. Y recuerda ejecutar php artisan config:clear después de cambiarlas.

El navegador muestra el listado de archivos. Estás apuntando a la carpeta del proyecto y no a public.

Para cerrar

Ya tienes Laravel instalado, el proyecto levantado y la base de datos conectada. Es la parte menos entretenida y la que evita que te trabes después.

Lo importante que quedó dicho: el .env nunca va al repositorio, y en producción APP_DEBUG va en false.

En la siguiente lección recorremos las carpetas del proyecto para saber qué es cada cosa y dónde va tu código.

Saludos y éxitos.