Actualización de Laravel 10 a 11 - Knowledge of Laravel

Introducción

Laravel 11 se lanzó en marzo de 2024. Esta guía explica los pasos para actualizar de Laravel 10.x a 11.x.

El tiempo estimado necesario para la actualización es de unos 15 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
Cambios en la estructura de la aplicación
Cambios en los tipos de coma flotante
Preservación de atributos al modificar columnas
Versión mínima de SQLite
Actualización de Sanctum

Impacto: medio

Carbon 3
Rehash de contraseñas
Rate limiting en segundos
Paquete Spatie Once

Impacto: bajo

Eliminación de Doctrine DBAL
Método casts de los modelos Eloquent
Cambios en tipos espaciales
Contract Enumerable
Contract UserProvider
Contract Authenticatable

Pasos de actualización

Actualización de dependencias

Impacto: alto Actualiza las siguientes dependencias en composer.json.

{
  "require": {
    "laravel/framework": "^11.0",
    "nunomaduro/collision": "^8.1"
  }
}

Si usas paquetes, actualízalos también.

{
  "require": {
    "laravel/breeze": "^2.0",
    "laravel/cashier": "^15.0",
    "laravel/dusk": "^8.0",
    "laravel/jetstream": "^5.0",
    "laravel/octane": "^2.3",
    "laravel/passport": "^12.0",
    "laravel/sanctum": "^4.0",
    "laravel/scout": "^10.0",
    "laravel/spark-stripe": "^5.0",
    "laravel/telescope": "^5.0",
    "livewire/livewire": "^3.4",
    "inertiajs/inertia-laravel": "^1.0"
  }
}

Después, instala las dependencias con el siguiente comando.

composer update

Si usas Cashier Stripe, Passport, Sanctum, Spark Stripe o Telescope, necesitas publicar las migraciones en tu aplicación.

php artisan vendor:publish --tag=cashier-migrations
php artisan vendor:publish --tag=passport-migrations
php artisan vendor:publish --tag=sanctum-migrations
php artisan vendor:publish --tag=spark-migrations
php artisan vendor:publish --tag=telescope-migrations

Si usas el instalador de Laravel, actualízalo también.

composer global require laravel/installer:^5.6

Si antes habías añadido manualmente doctrine/dbal, ya puedes eliminarlo. En Laravel 11 desaparece la dependencia con ese paquete.

Requisitos de versión de PHP

Impacto: alto Laravel 11 requiere PHP 8.2.0 o superior. Además, el cliente HTTP de Laravel requiere curl 7.34.0 o superior.

Cambios en la estructura de la aplicación

Impacto: alto En Laravel 11 se ha simplificado la estructura por defecto de la aplicación. Se ha reducido notablemente el número de service providers, middleware y archivos de configuración. Sin embargo, al actualizar una aplicación de Laravel 10 a Laravel 11 no se recomienda intentar migrar la estructura de la aplicación. Laravel 11 está diseñado para soportar también la estructura de aplicación de Laravel 10. Principales cambios estructurales:

Se ha cambiado para configurar middleware, exception handler y enrutamiento directamente en bootstrap/app.php
app/Http/Kernel.php se ha eliminado y se ha integrado en bootstrap/app.php
Se ha reducido el número de service providers por defecto y se gestionan en bootstrap/providers.php
Se ha reducido el número de archivos del directorio config/ (si es necesario, se pueden publicar con php artisan config:publish)

Cambios disruptivos (Breaking Changes)

Autenticación

Rehash de contraseñas

Impacto: medio En Laravel 11, si el “work factor” del algoritmo de hash ha cambiado, en el momento de la autenticación se hace un rehash automático de la contraseña. Si el nombre del campo de contraseña del modelo User no es password, indícalo con la propiedad authPasswordName del modelo.

class User extends Authenticatable
{
    protected $authPasswordName = 'custom_password_field';
}

Para desactivar esta funcionalidad, añade lo siguiente en config/hashing.php.

'rehash_on_login' => false,

Contract `UserProvider`

Impacto: bajo Se ha añadido el método rehashPasswordIfRequired al contract Illuminate\Contracts\Auth\UserProvider. Si tienes clases que implementan esta interfaz, añade el método.

public function rehashPasswordIfRequired(Authenticatable $user, array $credentials, bool $force = false);

Contract `Authenticatable`

Impacto: bajo Se ha añadido el método getAuthPasswordName al contract Illuminate\Contracts\Auth\Authenticatable. Si tienes clases que implementan esta interfaz, añade el método.

public function getAuthPasswordName()
{
    return 'password';
}

Base de datos

Versión mínima de SQLite

Impacto: alto Si usas SQLite, se requiere SQLite 3.26.0 o superior. Por cierto, en los nuevos proyectos de Laravel 11, el driver de base de datos por defecto pasa a ser SQLite.

Preservación de atributos al modificar columnas

Impacto: alto Al modificar una columna, debes indicar explícitamente todos los modificadores que quieras conservar tras la modificación. Los atributos no indicados se eliminan.

// En Laravel 10 se conservaban unsigned, default y comment
Schema::table('users', function (Blueprint $table) {
    $table->integer('votes')->nullable()->change();
});

// En Laravel 11 hay que indicar explícitamente todos los atributos
Schema::table('users', function (Blueprint $table) {
    $table->integer('votes')
        ->unsigned()
        ->default(1)
        ->comment('The vote count')
        ->nullable()
        ->change();
});

Si no quieres actualizar todas las migraciones existentes, haz un squash de las migraciones.

php artisan schema:dump

Cambios en los tipos de coma flotante

Impacto: alto Se han unificado los tipos de columna double y float de migraciones entre todas las bases de datos.

// double: ya no se necesitan los argumentos de total de dígitos ni decimales
$table->double('amount');

// float: solo un argumento opcional que indica la precisión
$table->float('amount', precision: 53);

Los métodos unsignedDecimal, unsignedDouble y unsignedFloat se han eliminado. Si quieres seguir usando el atributo unsigned, indícalo encadenando el método.

$table->decimal('amount', total: 8, places: 2)->unsigned();
$table->double('amount')->unsigned();
$table->float('amount', precision: 53)->unsigned();

Método `casts` de los modelos Eloquent

Impacto: bajo Se ha definido el método casts en la clase base de modelo Eloquent. Si en los modelos de tu aplicación tienes definida una relación llamada casts, colisiona con el nombre y hay que renombrar.

Driver dedicado para MariaDB

Impacto: muy bajo En Laravel 11 se ha añadido un driver de base de datos dedicado a MariaDB. Al conectar con MariaDB puedes usar el driver mariadb en la configuración.

'driver' => 'mariadb',

Cambios en tipos espaciales

Impacto: bajo Se han unificado los tipos de columna espaciales entre todas las bases de datos. En lugar de los métodos point, lineString, polygon, etc., usa geometry o geography.

$table->geometry('shapes');
$table->geography('coordinates');

Si quieres indicar explícitamente el tipo o el sistema de referencia espacial, pasa subtype y srid.

$table->geometry('dimension', subtype: 'polygon', srid: 0);
$table->geography('latitude', subtype: 'point', srid: 4326);

Eliminación de Doctrine DBAL

Impacto: bajo Laravel ha eliminado la dependencia de Doctrine DBAL. Se han eliminado las siguientes clases y métodos.

Schema\Builder::useNativeSchemaOperationsIfPossible()
Connection::getDoctrineConnection()
Connection::getDoctrineSchemaManager()
Connection::registerDoctrineType()
DatabaseManager::registerDoctrineType()
Clase Schema\Grammars\ChangeColumn
Clase Schema\Grammars\RenameColumn

Para inspeccionar la base de datos, usa los nuevos métodos nativos: Schema::getTables(), Schema::getColumns(), Schema::getIndexes(), Schema::getForeignKeys(), etc.

Fechas

Carbon 3

Impacto: medio Laravel 11 soporta tanto Carbon 2 como Carbon 3. Si vas a actualizar a Carbon 3, ten en cuenta que los métodos diffIn* pasan a devolver números de coma flotante y que los valores negativos representan la dirección temporal.

Rate limiting

Rate limiting en segundos

Impacto: medio En Laravel 11 se soporta rate limiting en segundos en lugar de en minutos. Los constructores de las clases GlobalLimit y Limit reciben ahora los valores en segundos.

// Antes (en minutos)
new GlobalLimit($attempts, 2); // 2 minutos

// Después (en segundos)
new GlobalLimit($attempts, 2 * 60); // 120 segundos

La propiedad decayMinutes de la clase Limit se ha renombrado a decaySeconds y pasa a ser en segundos. Los constructores de ThrottlesExceptions y ThrottlesExceptionsWithRedis también reciben ahora valores en segundos.

new ThrottlesExceptions($attempts, 2 * 60);
new ThrottlesExceptionsWithRedis($attempts, 2 * 60);

Paquetes

Publicación de service providers

Impacto: muy bajo Las nuevas aplicaciones de Laravel 11 no tienen el array providers en config/app.php. Si un paquete publica un service provider, usa el método ServiceProvider::addProviderToBootstrapFile.

use Illuminate\Support\ServiceProvider;

ServiceProvider::addProviderToBootstrapFile(Provider::class);

Sanctum

Actualización de Sanctum

Impacto: alto Laravel 11 no soporta Sanctum 3.x. Actualiza la dependencia de Sanctum en composer.json a ^4.0. Sanctum 4.0 ya no carga automáticamente las migraciones. Publícalas con el siguiente comando.

php artisan vendor:publish --tag=sanctum-migrations

Además, actualiza la configuración de middleware de config/sanctum.php.

'middleware' => [
    'authenticate_session' => Laravel\Sanctum\Http\Middleware\AuthenticateSession::class,
    'encrypt_cookies' => Illuminate\Cookie\Middleware\EncryptCookies::class,
    'validate_csrf_token' => Illuminate\Foundation\Http\Middleware\ValidateCsrfToken::class,
],

Paquete Spatie Once

Impacto: medio Laravel 11 ofrece ahora su propia función once. Si usas el paquete spatie/once, elimínalo de composer.json para evitar conflictos.

Conclusión

Laravel 11 incluye grandes cambios estructurales, pero como la estructura de aplicación de Laravel 10 sigue funcionando tal cual, se puede migrar de forma gradual.

Cambio	Impacto	Acción
Actualización de dependencias en `composer.json`	Alto	Cambiar a `laravel/framework ^11.0`
PHP 8.2 obligatorio	Alto	Comprobar la versión de PHP
Preservación de atributos al modificar columnas	Alto	Revisar los usos de `change()`
Cambios en tipos de coma flotante	Alto	Revisar las definiciones de columnas `double`/`float`
SQLite 3.26.0+ obligatorio	Alto	Comprobar la versión de SQLite
Sanctum `^4.0`	Alto	Publicar las migraciones
Carbon 3	Medio	Comprobar los valores de retorno de los métodos `diffIn*`
Rate limiting en segundos	Medio	Cambiar `decayMinutes` por `decaySeconds`
Eliminación de Doctrine DBAL	Bajo	Migrar a los métodos nativos de schema

Referencias

Guía oficial de actualización (inglés)
Diff del repositorio laravel/laravel (10.x → 11.x)
Laravel Shift: servicio comunitario que automatiza la actualización
Changelog de Carbon 3

​Introducción

​Actualización automatizada con Laravel Shift

​Cambios por nivel de impacto

​Impacto: alto

​Impacto: medio

​Impacto: bajo

​Pasos de actualización

​Actualización de dependencias

​Requisitos de versión de PHP

​Cambios en la estructura de la aplicación

​Cambios disruptivos (Breaking Changes)

​Autenticación

​Rehash de contraseñas

​Contract UserProvider

​Contract Authenticatable

​Base de datos

​Versión mínima de SQLite

​Preservación de atributos al modificar columnas

​Cambios en los tipos de coma flotante

​Método casts de los modelos Eloquent

​Driver dedicado para MariaDB

​Cambios en tipos espaciales

​Eliminación de Doctrine DBAL

​Fechas

​Carbon 3

​Rate limiting

​Rate limiting en segundos

​Paquetes

​Publicación de service providers

​Sanctum

​Actualización de Sanctum

​Paquete Spatie Once

​Conclusión

​Referencias

Introducción

Actualización automatizada con Laravel Shift

Cambios por nivel de impacto

Impacto: alto

Impacto: medio

Impacto: bajo

Pasos de actualización

Actualización de dependencias

Requisitos de versión de PHP

Cambios en la estructura de la aplicación

Cambios disruptivos (Breaking Changes)

Autenticación

Rehash de contraseñas

Contract `UserProvider`

Contract `Authenticatable`

Base de datos

Versión mínima de SQLite

Preservación de atributos al modificar columnas

Cambios en los tipos de coma flotante

Método `casts` de los modelos Eloquent

Driver dedicado para MariaDB

Cambios en tipos espaciales

Eliminación de Doctrine DBAL

Fechas

Carbon 3

Rate limiting

Rate limiting en segundos

Paquetes

Publicación de service providers

Sanctum

Actualización de Sanctum

Paquete Spatie Once

Conclusión

Referencias