​

Upgrade a Laravel 12

​

🎯 Qué cambió

​

🗺️ Mapa del esqueleto nuevo

​

Cosas que hay que saber antes de tocar bootstrap/app.php

• El stack global se declara entero con $middleware->use([...]), no con prepend/append. Cuatro middleware propios (RedirectOldDomain, ForceHttps, SecurityHeaders, BlockBlockedIps) van entre TrustProxies y HandleCors, y solo use() reproduce ese orden.
• InvokeDeferredCallbacks tiene que ir el primero. Sin él, defer() no ejecuta nada.
• Las rutas se registran todas dentro de then:, no con los argumentos web:/api:. El orden de registro decide qué ruta gana una URI, y routes/web.php también declara rutas bajo api/.
• El grupo api ya no trae throttle:api de serie en Laravel 11+. Se añade explícitamente.
• QrCodeServiceProvider no puede salir de bootstrap/providers.php: el paquete simplesoftwareio/simple-qrcode no declara extra.laravel, así que el auto-discovery no lo ve. maatwebsite/excel y ssheduardo/redsys-laravel sí lo declaran y por eso no están listados.

​

Health check

​

⚠️ Carbon 3: diffIn*() cambió de semántica

$ref   = Carbon::parse('2026-03-01');
$birth = Carbon::parse('1990-06-15');

$ref->diffInYears($birth);        // Carbon 2: 35   | Carbon 3: -35.70958904109589
$ref->diffInYears($birth, true);  // Carbon 3: 35.70958904109589

// ❌ En Carbon 3 devuelve negativo y la comparación deja de tener sentido
$minutes = now()->diffInMinutes($order->updated_at);
if ($minutes <= 60) { ... }   // -500 <= 60 se cumple SIEMPRE

// ✅
$minutes = (int) now()->diffInMinutes($order->updated_at, true);

• app/Services/RegistrationCategoryService.php — edad para la categoría del participante
• app/Http/Controllers/Checkout/CheckoutController.php — orden reciente aprobada, y noches de hotel
• app/Console/Commands/ExpireAbandonedRateChangeOrdersCommand.php — horas hasta la expiración

​

🖼️ La regla image ya no acepta SVG

'inputThumbnailImage' => 'image:allow_svg|mimes:jpeg,png,jpg,gif,svg|nullable',

​

🧪 PHPUnit 11

use PHPUnit\Framework\Attributes\Group;

#[Group('forms')]
class RegistrationFormFieldStateTest extends TestCase

​

🧰 Herramientas nuevas ya en uso

​

defer() — trabajo después de la respuesta

defer(fn () => GA4::sendEvent([...]));

​

Context — correlación de logs de pago

Context::add(['gateway' => 'redsys', 'order_id' => $order->id, 'internal_code' => $order->internal_code]);
Log::info('Redsys notify signature', ['isValid' => $isValid]);
// [...] local.INFO: Redsys notify signature {"isValid":true} {"gateway":"redsys","order_id":4321,...}

​

Number — formateo de cifras

Nota sobre el idioma. Laravel no sincroniza el locale de Number con el de la app: por defecto formatea en en (€1,234.56), que es justo lo que se mostraba antes. Si algún día se quiere formato español (1.234,56 €), se activa con un único Number::useLocale(...) en AppServiceProvider. Es un cambio visible para el usuario, así que es una decisión de producto, no del upgrade.

​

Dónde no usar Number

• app/Exports/: ahí number_format($v, 2, '.', '') produce valores máquina para CSV/Excel, y en FormFieldDisplayValueResolver se usa como clave de comparación. Cambiarlo rompe los exports y el emparejamiento de importes.
• Importes del checkout: el JavaScript los lee del DOM. public/assets/js/checkout/checkout.js hace parseFloat(document.getElementById('locatedPrice').textContent). Con formato español, parseFloat("1.234,56 €") devuelve 1.234 y el total se convertiría en 1,23 €. Cambiar esos importes exige reescribir antes el JS que los parsea.

​

✅ Cómo verificar el upgrade en local

composer validate --strict
./vendor/bin/pint --test
php artisan test --group=forms
php artisan test

php artisan about           # Laravel 12.x
php artisan route:list      # mismas rutas que antes + /up
php artisan schedule:list   # las 3 tareas con su cadencia original
php artisan l5-swagger:generate

​

📌 Notas

• Cada documentación de Swagger tiene ahora sus propias rutas. El paquete usa por defecto docs y api/oauth2-callback para todas las documentaciones, así que default y supervisor se pisaban entre sí, y la /docs propia de la app (definida en routes/web.php) acababa quedándose con la URI y borrando los nombres l5-swagger.*.docs. Como la vista de Swagger los resuelve con route(), /api/documentation y /api/docs-supervisor respondían 500. Ahora cada una declara su routes.docs y su routes.oauth2_callback en config/l5-swagger.php. Si añades una tercera documentación, dale las suyas.
• Las anotaciones OpenAPI @OA\ siguen funcionando. swagger-php 5 mantiene el soporte de docblocks; el JSON generado es byte-idéntico al de la versión anterior. No hace falta migrar a atributos #[OA\...].
• routes/channels.php sigue en el repo pero no se registra: broadcasting no se usa (Echo está comentado) y registrarlo añadiría un endpoint broadcasting/auth que antes no existía.