Cada dos años, el equipo de Symfony lanza una nueva actualización principal del framework. El actualizar nuestros proyectos a una versión principal es uno de los pasos más importantes de nuestras aplicaciones. Cada nueva versión de Symfony trae consigo nuevas características, mejoras de rendimiento y corrección de errores, por lo que puede requerir cambios en el código existente para adaptarse a los cambios y nuevas prácticas.

¿Qué hacer antes de actualizar?

Liberar nuestro código de funcionalidades obsoletas

Cuando actualizamos nuestra aplicación a una versión menor, podemos ver que hay varios avisos de funcionalidades obsoletas. En estos casos no es un problema pero, cuando actualizamos a una versión principal, todas estas funcionalidades obsoletas son eliminadas, por lo que hay que preparar el código y hacerlo compatible para la actualización.

Una de las maneras en las que podemos ver qué funcionalidades están obsoletas es navegar por nuestra aplicación y observar la barra de herramientas de Symfony. Ahí recibiremos los avisos de obsolescencias y ya sabremos qué es lo que hay que cambiar.

Es posible que en algunos casos estos avisos vengan de librerías de terceros, por lo que tenemos que asegurarnos de que esa librería está o va a ser actualizada.

También disponemos de una herramienta llamada Rector. Esta herramienta nos proporciona actualizaciones y refactorizaciones automáticas. Una herramienta bastante interesante en el mundo Symfony.

Si usas PHPUnit para tus test, revisa el post oficial de Symfony.

Una vez hemos liberado nuestra aplicación de mensajes de funcionalidades obsoletas, podemos continuar con la actualización 🎉.

Actualizar vía Composer

Llega el momento de actualizar nuestra versión de Symfony. Es un proceso más sencillo de lo que parece.

En nuestro composer.json debemos cambiar las versiones de las librerías que empiecen con symfony/. Por ejemplo, nos encontramos con lo siguiente:

"symfony/console": "6.4.*"

Bastaría con cambiar la versión 6.4.* a la 7.0.*, por lo que quedaría de la siguiente manera:

"symfony/console": "7.0.*"

Para continuar, debemos dirigirnos al final de nuestro composer.json, en el cual encontraremos, en el bloque extra, nuestra versión de Symfony. Bastaría con cambiar la versión a la 7.0.* y dejarlo de la siguiente manera:

"extra": {
      "symfony": {
          "allow-contrib": false,
      	  "require": "7.0.*"
      }
  }

Ahora viene el momento de la verdad, usar Composer para descargar las nuevas versiones. Hay que lanzar lo siguiente en nuestra terminal:

composer update "symfony/*"

Si al actualizar con Composer nos da un error de dependencias, lanzaríamos lo siguiente:

composer update "symfony/*" --with-all-dependencies

Desde Symfony nos recomiendan, como buena práctica al actualizar a una versión mayor, limpiar la caché de los directorios de forma manual:

# Para Linux o Mac
rm -rf var/cache/*

# Para Windows
rmdir /s /q var\cache\*

Si queremos actualizar el resto de librerías, bastaría con lanzar un update:

composer update

Actualizar recetas

Puede darse el caso de que al actualizar nuestra versión de Symfony, haya una actualización de receta. Gracias a Symfony Flex es bastante sencillo actualizarla:

Recuerda hacer commit de los cambios, de lo contrario no podrás actualizar.

# Elegir la receta a actualizar
composer recipes:update

# Actualizar una receta específica
composer recipes:update symfony/framework-bundle

# Listar las recetas instaladas y ver si tienen actualizaciones disponibles
composer recipes

# Mostrar información detallada de una receta específica
composer recipes symfony/framework-bundle

Actualizar el código

En algunos casos, es posible que la próxima versión principal rompa la compatibilidad con versiones anteriores. Asegúrate de leer UPGRADE-X.0.md en el repositorio de Symfony para cualquier ruptura de compatibilidad.

Symfony 6 y 7 añadieron tipos de retorno nativos de PHP a casi todos los métodos. En PHP, si el padre tiene una declaración de tipo de retorno, cualquier clase que implemente o anule el método también debe tener el tipo de retorno. Sin embargo, puedes agregar un tipo de retorno antes de que el padre agregue uno. Esto significa que es importante agregar los tipos de retorno nativos de PHP a tus clases antes de actualizar a Symfony 6 o 7. De lo contrario, obtendrás errores de declaración incompatibles.

Para facilitar este proceso, Symfony proporciona un script que puede agregar automáticamente los tipos de retorno a tus clases. Asegúrate de haber instalado el componente symfony/error-handler y luego ejecuta el script después de generar un mapa completo de clases usando Composer. Esto ayudará a corregir cualquier método incompatible:

composer dump-autoload -o
./vendor/bin/patch-type-declarations

Con todos estos pasos finalizaremos la actualización de nuestra aplicación Symfony.

Fuentes: Symfony

Imagen generada con DALL·E 3