Introducción
Laravel 12 se lanzó en febrero de 2025. Esta guía explica los pasos para actualizar de Laravel 11.x a 12.x.El tiempo estimado necesario para la actualización es de unos 5 minutos. Sin embargo, el impacto de los cambios disruptivos en tu aplicación varía según el tamaño y las funcionalidades utilizadas.
Actualización automatizada con Laravel Shift
Puedes automatizar la actualización con Laravel Shift. Shift actualiza automáticamente las dependencias y los archivos de configuración de tu aplicación.Cambios por nivel de impacto
Impacto: alto
- Actualización de dependencias
- Actualización del instalador de Laravel
Impacto: medio
- Trait
HasUuidsde Eloquent y UUIDv7
Impacto: bajo
- Carbon 3
- Mapeo por índice de resultados en Concurrency
- Resolución de dependencias de clase en el contenedor
- Exclusión de SVG en la validación de imagen
- Ruta raíz por defecto del disco de sistema de archivos local
- Inspección de base de datos con múltiples schemas
- Merge de peticiones con arrays anidados
Pasos de actualización
Actualización de dependencias
Impacto: alto Actualiza las siguientes dependencias encomposer.json.
Actualización del instalador de Laravel
Impacto: alto Si creas nuevas aplicaciones de Laravel con el CLI del instalador, actualízalo a la versión compatible con Laravel 12.x y con los nuevos starter kits. Si lo instalaste concomposer global require:
php.new, ejecuta el comando de reinstalación según tu SO.
- macOS
- Windows PowerShell
- Linux
Nuevos starter kits
En Laravel 12 se han introducido nuevos starter kits que sustituyen a Breeze y Jetstream. Al ejecutarlaravel new puedes elegir de forma interactiva el stack de frontend.
Starter kits disponibles:
- React: Inertia 2, React 19, TypeScript, Tailwind 4, shadcn/ui
- Vue: Inertia 2, Vue Composition API, TypeScript, Tailwind 4, shadcn-vue
- Svelte: Inertia 2, Svelte 5, TypeScript, Tailwind 4, shadcn-svelte
- Livewire: Livewire, Tailwind 4, Flux UI
Si estás actualizando una aplicación existente, no hace falta reintroducir el starter kit. Es un cambio para proyectos nuevos.
Cambios disruptivos (Breaking Changes)
Eloquent
Trait HasUuids y UUIDv7
Impacto: medio
El trait HasUuids ahora devuelve UUID v7 (UUID ordenables). Si quieres mantener el comportamiento anterior de UUID v4 ordenables, cambia al trait HasVersion4Uuids.
HasVersion7Uuids, cámbialo al trait HasUuids (ahora tiene el mismo comportamiento).
Validación
Exclusión de SVG en la validación de imagen
Impacto: bajo La regla de validaciónimage ya no permite SVG por defecto. Si quieres permitir SVG, indícalo explícitamente.
Storage
Ruta raíz por defecto del disco de sistema de archivos local
Impacto: bajo Si no defines explícitamente el discolocal en la configuración de filesystems, la ruta raíz por defecto ha cambiado de storage/app a storage/app/private.
Para mantener el comportamiento anterior, define el disco local explícitamente en el archivo de configuración.
Base de datos
Inspección de base de datos con múltiples schemas
Impacto: bajoSchema::getTables(), Schema::getViews() y Schema::getTypes() devuelven ahora por defecto los resultados de todos los schemas. Para acotar a un schema concreto, pasa el argumento schema.
Schema::getTableListing() devuelve ahora por defecto los nombres de tabla calificados con el schema.
Cambios en la firma del constructor de Database
Impacto: muy bajo Los constructores deIlluminate\Database\Schema\Blueprint e Illuminate\Database\Grammar requieren ahora una instancia de Connection como primer argumento.
| API | Estado |
|---|---|
Blueprint::getPrefix() | Obsoleta |
Connection::withTablePrefix() | Eliminada |
Grammar::getTablePrefix() / setTablePrefix() | Obsoletas |
Grammar::setConnection() | Eliminada |
Concurrency
Mapeo por índice de resultados
Impacto: bajo Al pasar un array asociativo aConcurrency::run(), los resultados se devuelven ahora con la clave correspondiente.
Contenedor
Valor por defecto en la resolución de dependencias de clase
Impacto: bajo El contenedor de DI ahora respeta los valores por defecto de las propiedades de clase al resolver una instancia de clase.Request
Merge de peticiones con arrays anidados
Impacto: bajo Ahora puedes hacer merge con$request->mergeIfMissing() de datos de array anidados usando notación por puntos. Antes, las claves con notación por puntos se creaban tal cual como claves de nivel superior.
Enrutamiento
Prioridad de rutas
Impacto: bajo Se ha unificado el comportamiento con y sin caché cuando hay varias rutas con el mismo nombre. Incluso sin caché de rutas, ahora tiene prioridad la ruta registrada primero, no la última.Autenticación
Cambios en el constructor de DatabaseTokenRepository
Impacto: muy bajo
El constructor de Illuminate\Auth\Passwords\DatabaseTokenRepository recibe ahora el parámetro $expires en segundos en lugar de en minutos.
Carbon 3
Impacto: bajo Se ha eliminado el soporte de Carbon 2.x. Todas las aplicaciones de Laravel 12 requieren Carbon 3.x.Conclusión
Laravel 12 es una versión que se puede actualizar de forma relativamente fluida. Resumen de los principales puntos a tener en cuenta.| Cambio | Impacto | Acción |
|---|---|---|
Actualización de dependencias en composer.json | Alto | Cambiar a laravel/framework ^12.0 |
| Actualización del instalador de Laravel | Alto | composer global update |
HasUuids → UUIDv7 | Medio | Si es necesario, cambiar a HasVersion4Uuids |
Exclusión de SVG en la validación image | Bajo | Añadir allow_svg si quieres permitir SVG |
| Cambio de la ruta raíz por defecto del disco local | Bajo | Indicarla explícitamente en el archivo de configuración |
| Carbon 3 obligatorio | Bajo | Comprobar la compatibilidad de la API |
Referencias
- Guía oficial de actualización (inglés)
- Diff del repositorio laravel/laravel (11.x → 12.x)
- Nuevos starter kits
- Laravel Shift: servicio comunitario que automatiza la actualización
- Guía de migración de Carbon 3