Crear un proyecto en Laravel es fácil. Convertirlo en una aplicación segura, comprensible y preparada para producción es otra historia.

Esta guía propone recorrer el camino completo: desde comprobar los requisitos del equipo y ejecutar el primer comando hasta desplegar una aplicación real, configurar sus procesos y resolver los errores que normalmente aparecen fuera de los tutoriales.

No construiremos una demostración que termina después de guardar tres registros. Desarrollaremos un sistema de gestión de incidencias con usuarios, prioridades, estados, comentarios, permisos, historial de acciones y una base preparada para crecer.

El objetivo no es memorizar comandos de Artisan. Es comprender cómo encajan las piezas de Laravel y aprender a tomar decisiones que sigan siendo correctas cuando la aplicación llegue a producción.

Qué construiremos

El proyecto de esta ruta será una aplicación web en la que una persona autenticada podrá registrar una incidencia, consultar su estado y participar mediante comentarios. Los usuarios autorizados podrán clasificarla, asignarla, modificar su prioridad y cerrarla. Cada operación relevante dejará un registro para poder reconstruir lo ocurrido.

La primera versión incluirá:

  • Registro e inicio de sesión.
  • Usuarios con roles y permisos diferenciados.
  • Creación, consulta, edición y cierre de incidencias.
  • Estados y prioridades relacionados mediante identificadores.
  • Comentarios asociados a cada incidencia.
  • Validación mediante Form Requests.
  • Autorización para impedir accesos indebidos.
  • Registro de acciones importantes.
  • Manejo de errores sin mostrar una página blanca al usuario.
  • Pruebas esenciales de autenticación, permisos y operaciones.
  • Preparación y despliegue en un servidor Linux.
  • Workers de colas y tareas programadas gestionados como servicios.

Usaremos Laravel como aplicación full stack, con rutas, controladores, Eloquent y vistas Blade. Esta elección permite aprender el ciclo completo de una petición sin ocultarlo detrás de una SPA. Más adelante podremos convertir Laravel en una API o conectar Angular, Vue, React o una aplicación móvil sin desperdiciar lo aprendido.

A quién está dirigida esta ruta

La serie está pensada para quien ya conoce los fundamentos de PHP y quiere empezar a trabajar con Laravel de manera ordenada. También será útil si ya has creado algún CRUD, pero todavía tienes dudas sobre estructura, relaciones, permisos, despliegue o mantenimiento.

No necesitas dominar Laravel. Sí conviene comprender variables, funciones, clases, formularios, consultas SQL básicas y el funcionamiento general de una aplicación web.

Tecnologías que utilizaremos

Tecnología Uso dentro del proyecto
Laravel 13 Estructura de la aplicación, autenticación, validación, autorización, colas y tareas.
PHP 8.3 o superior Lenguaje requerido por Laravel 13.
Composer Dependencias PHP y creación del proyecto.
MySQL o MariaDB Persistencia de usuarios, incidencias, comentarios, permisos y registros.
Blade Vistas renderizadas por Laravel.
Vite y Node.js o Bun Compilación de CSS y JavaScript.
Apache o Nginx Servidor web en producción.
Git Control de versiones y despliegues reproducibles.

Laravel 13 requiere PHP 8.3 o superior y varias extensiones habituales, entre ellas cURL, DOM, Fileinfo, Mbstring, OpenSSL, PDO, Session, Tokenizer y XML. En el primer capítulo comprobaremos cada requisito antes de instalar nada.

La arquitectura que iremos construyendo

Una petición no debería convertirse en una cadena de consultas, validaciones y decisiones mezcladas dentro de una vista. A lo largo de la ruta distribuiremos cada responsabilidad en el lugar adecuado:

  1. La ruta recibe una URL y dirige la petición.
  2. El middleware comprueba sesión y condiciones de acceso.
  3. El Form Request valida y autoriza los datos de entrada.
  4. El controlador coordina la operación.
  5. Los modelos y relaciones representan los datos.
  6. Las políticas deciden quién puede realizar cada acción.
  7. Los eventos o servicios registran efectos secundarios cuando sea necesario.
  8. La vista presenta el resultado sin contener lógica de negocio innecesaria.

No añadiremos capas por moda. Empezaremos con la estructura que Laravel proporciona y extraeremos responsabilidades cuando exista una razón concreta para hacerlo.

Índice completo de la guía

Este artículo funcionará como punto de entrada. Cada capítulo tendrá su propia publicación, código verificable, errores frecuentes y un enlace para continuar. Conforme se publiquen, este índice se actualizará con sus enlaces definitivos.

1. Qué vamos a construir

Definiremos el alcance del gestor de incidencias, sus tipos de usuario y las operaciones que debe permitir. Antes de abrir el editor convertiremos una idea general en requisitos que se puedan implementar y comprobar.

2. Requisitos del entorno

Comprobaremos PHP, Composer, extensiones, Node.js o Bun, MySQL y Git. Veremos cómo detectar incompatibilidades antes de que aparezcan errores confusos durante la instalación.

3. Crear el proyecto

Crearemos la aplicación, revisaremos las decisiones del instalador y levantaremos el entorno de desarrollo. También diferenciaremos el servidor integrado de PHP de un servidor web de producción.

laravel new gestor-incidencias
cd gestor-incidencias
npm install && npm run build
composer run dev

4. Comprender la estructura de carpetas

Recorreremos app, bootstrap, config, database, public, resources, routes, storage y tests. La meta será saber dónde buscar y dónde colocar una nueva responsabilidad.

5. Configurar el archivo .env sin exponer secretos

Explicaremos qué información pertenece al entorno, por qué .env no debe subirse al repositorio y cómo trabaja Laravel con sus archivos de configuración. También veremos qué ocurre después de ejecutar config:cache.

6. Crear la base de datos y un usuario limitado

Crearemos una base de datos y un usuario exclusivo para la aplicación. No utilizaremos root como credencial permanente: una aplicación solo debe disponer de los permisos que necesita.

7. Diseñar las tablas antes de escribir código

Transformaremos los requisitos en entidades y relaciones. Usuarios, incidencias, estados, prioridades, comentarios, roles y registros tendrán identificadores y responsabilidades claras. Evitaremos relaciones frágiles basadas en comparar textos.

8. Migraciones y claves foráneas

Crearemos el esquema de forma reproducible, elegiremos tipos adecuados y definiremos claves foráneas, índices y reglas de eliminación. También aprenderemos cuándo una migración debe modificarse y cuándo conviene crear una nueva.

9. Modelos y relaciones Eloquent

Implementaremos relaciones uno a muchos y muchos a muchos. Revisaremos asignación masiva, casts, consultas eficientes y carga anticipada para evitar el problema N+1.

10. Rutas y controladores

Diseñaremos URLs legibles y controladores con responsabilidades pequeñas. Compararemos rutas individuales con recursos y utilizaremos nombres de ruta para no acoplar las vistas a direcciones escritas manualmente.

11. Form Requests y validación

Sacaremos la validación del controlador, personalizaremos mensajes y diferenciaremos validar datos de autorizar una acción. También conservaremos la entrada del formulario cuando exista un error.

12. CRUD de incidencias

Uniremos las piezas para listar, crear, mostrar, editar y cerrar incidencias. Añadiremos filtros, paginación, mensajes de confirmación y estados vacíos útiles.

13. Login y protección de rutas

Incorporaremos autenticación con un starter kit oficial y revisaremos sesiones, CSRF, regeneración del identificador de sesión y protección de páginas privadas.

14. Roles y permisos

Separaremos autenticación de autorización. Estar identificado no significa poder modificar cualquier incidencia. Implementaremos roles, permisos y políticas sin depender de condiciones repetidas por todas las vistas.

15. Manejo profesional de errores

Prepararemos respuestas diferentes para errores de validación, recursos inexistentes, accesos prohibidos y fallos inesperados. El usuario recibirá un mensaje útil y el detalle técnico quedará en los logs, sin exponer rutas, consultas ni credenciales.

16. Registro de acciones

Guardaremos inicios y cierres de sesión, cambios de estado, asignaciones y acciones administrativas. Diferenciaremos los logs técnicos de una auditoría funcional consultable desde la aplicación.

17. Pruebas esenciales

Crearemos pruebas para los recorridos que más daño causarían si dejaran de funcionar: autenticación, aislamiento entre usuarios, permisos, validación y cambios de estado. No perseguiremos una cifra decorativa de cobertura; protegeremos comportamientos importantes.

18. Preparación para producción

Revisaremos variables del entorno, dependencias sin paquetes de desarrollo, compilación de recursos, migraciones, cachés, modo de depuración, logs, copias de seguridad y comprobación de salud.

19. Despliegue con Apache y Nginx

Configuraremos ambos servidores para dirigir las peticiones a public/index.php. Nunca expondremos la raíz completa del proyecto ni moveremos index.php fuera de public.

20. Permisos de storage y bootstrap/cache

Laravel necesita escribir en storage y bootstrap/cache. Veremos cómo asignar propietario y permisos suficientes sin convertir todo el proyecto en escribible para cualquier usuario.

21. Colas, cron y procesos residentes

Enviaremos operaciones lentas a una cola, programaremos tareas y mantendremos los workers activos mediante Supervisor o systemd. Una terminal abierta no será nuestra estrategia de producción.

22. Seguridad posterior al despliegue

Revisaremos HTTPS, cabeceras, actualizaciones, privilegios mínimos, rate limiting, copias de seguridad, monitorización, secretos y exposición de errores. La seguridad será un proceso, no una casilla marcada al terminar.

23. Errores frecuentes y soluciones

Reuniremos fallos reales, sus síntomas y el método para encontrar la causa. La meta no será copiar una solución al azar, sino aprender a leer el mensaje, separar capas y comprobar hipótesis.

24. Próximos pasos

Con la aplicación funcionando evaluaremos extensiones razonables: API con Sanctum, notificaciones, búsqueda, archivos adjuntos, eventos en tiempo real, métricas y un frontend independiente.

Los errores reales también forman parte del curso

Las aplicaciones no fallan únicamente en los ejemplos preparados. Por eso documentaremos problemas que aparecieron durante proyectos reales y que pueden ahorrar horas de búsqueda.

Variables de base de datos comentadas en .env

Una configuración aparentemente correcta puede estar ignorada porque sus líneas comienzan con #. Laravel utilizará entonces otros valores o configuraciones predeterminadas. Aprenderemos a distinguir un problema de credenciales de un problema de configuración no cargada.

Laravel no puede escribir en storage/logs

Un error de permisos puede ocultar el fallo original porque la aplicación tampoco consigue escribirlo en el log. Revisaremos propietario, grupo, permisos y usuario efectivo del servidor web antes de aplicar cambios indiscriminados.

Access denied for user root@localhost

MySQL puede autenticar a root mediante el sistema operativo y rechazar la conexión desde PHP. La solución correcta en producción no es debilitar esa cuenta, sino crear credenciales limitadas para la aplicación.

Desarrollo no es producción

php artisan serve, Vite en modo desarrollo y un worker ejecutado en una terminal son herramientas válidas durante la construcción. En producción necesitaremos un servidor web, recursos compilados, procesos supervisados y una configuración que sobreviva a reinicios.

El DocumentRoot debe apuntar a public

Servir la raíz completa del proyecto puede exponer archivos sensibles. Apache o Nginx deben publicar únicamente el directorio public y enviar las peticiones a public/index.php.

Los workers deben reiniciarse después de un despliegue

Los procesos de larga duración pueden continuar ejecutando código antiguo después de actualizar los archivos. Veremos cómo recargarlos de forma controlada y cómo conseguir que vuelvan a levantarse si fallan o si el servidor se reinicia.

Cómo trabajaremos en cada capítulo

Cada entrega seguirá la misma estructura:

  1. Objetivo concreto.
  2. Decisiones y motivo de cada una.
  3. Implementación paso a paso.
  4. Código completo de los archivos importantes.
  5. Comandos que deben ejecutarse.
  6. Pruebas para comprobar el resultado.
  7. Errores frecuentes y diagnóstico.
  8. Resultado esperado.
  9. Enlace al siguiente capítulo.

Cuando un comando pueda borrar datos, cambiar permisos o afectar producción, lo indicaremos antes de ejecutarlo. También separaremos los valores de ejemplo de los datos secretos que cada persona debe configurar en su entorno.

Qué aprenderás al completar la ruta

Al terminar no solo tendrás un gestor de incidencias funcionando. Deberías ser capaz de:

  • Crear y configurar una aplicación Laravel desde cero.
  • Diseñar una base de datos antes de programar el CRUD.
  • Representar relaciones mediante claves e identificadores estables.
  • Validar entradas y autorizar operaciones correctamente.
  • Proteger información de usuarios y limitar el acceso.
  • Investigar errores mediante logs y comprobaciones reproducibles.
  • Escribir pruebas que protejan los recorridos importantes.
  • Desplegar la aplicación sin exponer archivos sensibles.
  • Mantener colas y tareas programadas como servicios.
  • Preparar una base que pueda crecer hacia API, SPA o tiempo real.

Decisiones que no tomaremos a ciegas

Laravel ofrece muchas opciones: Blade, Livewire, Inertia, APIs, distintos sistemas de caché, colas y plataformas de despliegue. No intentaremos utilizarlas todas en el primer día.

Empezaremos con una arquitectura suficiente para el problema actual. Cuando añadamos una tecnología, deberá responder a una necesidad observable. Esa disciplina hace que un proyecto sea más fácil de comprender, probar y mantener.

Fuentes y versión de referencia

La serie estará basada en Laravel 13 y se contrastará con la documentación oficial de Laravel 13. Cuando una instrucción dependa de la versión, quedará indicada expresamente.

También mantendremos una fecha de revisión en cada capítulo. Si utilizas Laravel 12, muchas ideas seguirán siendo aplicables, pero deberás comprobar las diferencias señaladas antes de copiar comandos o configuraciones.

Comenzamos

En el primer capítulo instalaremos y verificaremos el entorno. No daremos por hecho que PHP, Composer, las extensiones, Node.js y MySQL están listos: aprenderemos a comprobar cada pieza y a interpretar los resultados.

Esta página será el índice vivo de la serie. Guarda el enlace y vuelve conforme se publiquen los capítulos. Cada nueva entrega quedará conectada aquí para que puedas avanzar desde una instalación limpia hasta una aplicación desplegada y mantenible.

Construiremos una aplicación real, cometeremos errores reales y aprenderemos a resolverlos sin convertir el proyecto en una colección de parches.