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.
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 ;).
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).
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!
What a Symfony developer should know about the framework: News, Jobs, Tweets, Events, Videos,...