Symfony Flex makes it easy to install a package and get everything you need to start working immediately: new config files, changes to .env, Docker configuration and more. The idea is so powerful that symfony/skeleton - the repository used for new Symfony apps - starts empty other than composer.json! Familiar files like src/Kernel.php, bin/console and config/services.yaml are added to your project via recipes.

The "ingredients" to these recipes can be found at https://github.com/symfony/recipes and https://github.com/symfony/recipes-contrib. Over time, as Symfony adds new features or adopts new best-practices, the recipes change. And while you don't need to update these files, it's the best way to take advantage of new features and keep your Symfony app "feeling" standard.

Hello "recipes: update"!

Upgrading to a new version of Symfony is a well-documented process. But until now, there wasn't a great way to update your already-installed recipes. You could use composer recipes:install symfony/framework-bundle --force, but that simply re-installs the recipe, completely overwriting your files and custom changes with the latest version. That made the upgrade process brittle and tricky. Not a good user experience!

And so, starting in symfony/flex 1.18.0 or 2.1.0, a new composer command is now available: recipes:update. This command is smart: it generates a "diff" between the originally-installed version of recipe and the latest version, then leverages git to apply that patch. In other words, upgrading recipes is as simple and robust as merging two branches together with git! Most of the time the changes apply cleanly. But if they don't, you get a familiar git-style conflict that you can resolve.

Well then... let's see it! In this example, I'm updating the symfony/framework-bundle recipe - the most complex recipe - which is 18 months and 4 Symfony versions out-of-date in my project!

Once you've reviewed the changes, commit them like normal, then... back to work! Either to upgrade more recipes, work on your app, or contribute back to Symfony ;).

The CHANGELOG

After updating a recipe, you can run git status and git diff --cached path/to/file to see what updated. But while this will tell you what changed, it won't tell you why that change was introduced.

Fortunately, the recipes:update command includes a CHANGELOG at the bottom, with a summary of all the pull requests that made changes to the recipe since you originally installed it. For example:

  • [5.2] Remove trusted-proxies/hosts from recipes (#790)
  • [symfony/framework-bundle] Add config/preload.php (#825)
  • Disable "http_method_override" by default (#892)
  • [FrameworkBundle] Replace deprecated `storage_id` by `storage_factory… (#898)
  • Leverage the new Runtime component (#787)

In most modern terminals, you can click the pull request number - e.g. #790 - to jump to that pull request on GitHub (you may need to hold Ctrl or Cmd and then click, depending on your terminal).

When Should I Run recipes:update?

Feel free to run recipes:update command as often as you want. To update everything, run it repeatedly until the list is empty! It's safe, and you get to review all changes before you commit.

But the most important time to upgrade your recipes is after upgrading a package (like Symfony) to a new minor (e.g. 5.3 -> 5.4) or major (e.g. 5.4 -> 6.0) version. That's the most common time when a recipe will have important upgrades.

Have fun and happy recipe-updating!

Published in #Symfony