symfony
symfony copied to clipboard
symfony
[RFC] Switch from Yaml to PHP files for skeleton configurations
Description
I currently did not yet find a discussion about this topic. I know that all internal configuration of Symfony was already converted from YAML to PHP so internal components do not longer require the symfony/yaml package. Was myself expecting it will also happening in Symfony 6 for the skeleton files.
From my point of view, I think it also make in future sense to go with PHP files also in projects and so provide also the recipes in the php format.
So part of this issue is first to kickoff the discussion about Yaml vs PHP in project configuration. What DX issues Yaml and what DX issues PHP solves.
Beside that discussion I think it would be great that we maybe provide a current "experimental" recipe repositories providing php instead of yaml files. Here maybe already existing tool from @TomasVotruba could be used the ConfigTransformer. So both can exist side by side and are updated automatically by one as a source of true. And even if we don't go with php as default in symfony skeleton it would still be possible for projects using php instead of yaml without any disadantages.
Then we would have a github.com/symfony/recipes-php and github.com/symfony/recipes-contrib-php repository. And as I know symfony/flex already make it possible to configure other "endpoints" for recipes so it should be required there.
Example
No response
https://github.com/symfony/symfony/discussions/42388 https://github.com/symfony/symfony/discussions/42624
do not longer require the symfony/yaml package
sounds noble :+1:
ideally i'd like to see eg. flex handle the conversion on-the-fly/on-demand
I second this, PHP config should definitely have recipe syncing work out of the box. I'm not totally sold with the multi-repository approach though as it would make recipe discovery harder, thus might be confusing.
Here, we are talking about 2 very different things: services configuration in core is now using PHP, but recipes are about semantic configuration, for which we don't have a good XP in PHP.
Now that we have config builders we could ship both yaml and php config files in recipes, then we could use an option (i.e using composer extra) to define which preferred format should be used by Flex.
@HeahDude Why I had also that kind of things first in mind. It actually would be a bc break. And at current state recipes are not versionated and symfony/flex currently always access the main branch. So to make that break we would need to keep the main branch as compatible version to older symfony/flex versions and use another branch e.g. 2.0 as the recipe source for symfony/flex version handling that. Related comment here.
The problem with the ConfigBuilders would be that we would need to manually write them as I think there is currently no converter available for them yet and the config transformer doesn't yet support it. But yeah would be something which could be tackled.
@fabpot understand that point. That is also why I was thinking about experimental repositories which people can then just configure in the composer.json. Via the already configurable endpoint: https://github.com/symfony/flex/blob/d1a692369be53445af6e391170b509d7f5d026cf/src/Downloader.php#L61
it would be great that we maybe provide a current "experimental" recipe repositories providing php instead of yaml files
I would be happy to see such a repo be created by the community first. The way I see this repo is the same as yours I think: symfony/recipes (and also recipes-contrib btw) would somehow be auto-compiled into PHP recipes, and ppl could opt-in for this source of recipes instead of the default one.
No need for anything on the symfony/ org on github, this can be experimented anywhere now that everything related to flex is open-sourced.
I don't think we need to keep track of this effort on this repo btw - that's not related to symfony/symfony.
@nicolas-grekas sounds fair for me. Maybe I will experiment with it the next days, help welcome! If it works maybe the @friendsofsymfony organizsation could be a place for it at current state :)
I did start experementing with it at current state in a repository of mine by using the ConfigTransformer: https://github.com/alexander-schranz/symfony-recipes-php/pull/1
I also started a poll on twitter to get some feedback if people are interested into using PHP instead of Yaml in Symfony: https://twitter.com/alex_s_/status/1552265436380950528
Yaml is more understandable and simply to reading by human Sounds bad (I remembered the configs in zf 🥲)
Thanks for the experiment @alexander-schranz. Let's iterate on https://github.com/alexander-schranz/symfony-recipes-php and reopen the discussion later, on the recipes repository.
Make sense to continue there. Currently it doesn't look too bad, we need to fix some issues on the config-transformer, most of them should not be too much a problem.
But one is that we would require a new yaml parser for the config-transformer, currently symfony/yaml is used but as already discussed in #22516 symfony/yaml does not support to parse it with comments. And losing comments would make the php config less understandable as the yaml format. But just things which are able to solve and need some time to implement.
If somebody want to help let me know or just checkout the current linked issues/reproducer in the PR checklist for the symplify/symplify config-transformer: https://github.com/alexander-schranz/symfony-recipes-php/pull/1
Little and most last update here I created a "skeleton" which will use automatically the new PHP Recipes repository which people can use to play around with it:
composer create-project schranz/symfony-php-website-skeleton
composer create-project schranz/symfony-php-skeleton
I hope to continue working on the "auto update" of the two repository:
- https://github.com/alexander-schranz/symfony-recipes-php
- https://github.com/alexander-schranz/symfony-recipes-php-contrib
We could solve most of the config-transformers issues and so all configs should now work. Beside the "auto update" the missing issues is still find a way to keep / convert comments.
Further discussion will be done and updates will be done over alexander-schranz/symfony-recipes-yaml-to-php-converter repository (feel free to subscribe the issues), and if all work like expected there will maybe be in future some discussion in symfony/flex repo about it.
A short update. I moved all relevant packages to an own organisation to have a better overview: https://github.com/symfony-php-recipes. It provides the two recipes repositories here:
- https://github.com/symfony-php-recipes/symfony-recipes-php
- https://github.com/symfony-php-recipes/symfony-recipes-php-contrib
The relevant code which does the YAML -> PHP Config convert is in:
- https://github.com/symfony-php-recipes/symfony-recipes-yaml-to-php-converter
And the two skeletons are here:
- https://github.com/symfony-php-recipes/symfony-php-skeleton
- https://github.com/symfony-php-recipes/symfony-php-website-skeleton
I even got time to test composer recipes:update command which was provides by @weaverryan in https://github.com/symfony/flex/pull/845 and it worked like expected:
Wow! That's a lot of impressive steps forward in this complex process - nice job 👍
Next question I can think of is this: what if we decide to adopt PHP config (maybe with some period of offering both PHP and YAML config) and, in symfony/framework-bundle, we decide to ship with the nicer-version of the config - i.e. this https://symfony.com/blog/new-in-symfony-5-3-config-builder-classes
For users, they would have a painful recipes:update after we did this. WDYT about this? Moving to PHP config would be easier if we only used the "array" format of PHP config. But the builder format would be much nicer.
Moving to PHP config would be easier if we only used the "array" format of PHP config. But the builder format would be much nicer.
The existing recipes:update would still be as painful for them with simple arrays, because git will not merge automatically a YAML file and a PHP file containing the array.
So in any case, it would require Flex to contain a special converter to be able to convert the local YAML file to PHP before applying the new recipe. The only difference is how hard it is to implement that converter. But that's a pain that is on us, not on final users (they will use the converter, not implement them, and maybe they won't even know they used it through Flex)
@weaverryan as I did understand the whole recipes:update like shown above works with a git diff similar process and conflict handling. So from the recipes:update point of view I don't think there will be much different between PHP Array Config vs PHP Builder Config aslong as every option is in an own line, which as we are generating the recipes can be forced.
The more complex process will be to achieve that we can provide from yaml or php array config based recipes convert to the Builder classes to automate this process.
Another complex task will be how we can provide an easy way to migrate exist Yaml based projects to a PHP config based project. I think Symfony should provide atleast for a long time both yaml and php based recipes. With the bot which generates the PHP based configuration this should be no problem and the yaml recipes are just the source of truth. Providing both allow that if somebody want to migrate from Yaml to PHP, they can first upgrade there Yaml based configs to the latest version and then they can use the config-transformer to convert there Yaml to PHP based configurations. But that process has more todo about documentation for existing projects then. I already have that on my list as I want to convert our own @sulu website to PHP this way.
Addition:
So planned from my side is that switching from Yaml to PHP is an active process by the dev/user that way it is more easy and reproducable for that user. I would not make it any force here that we e.g. force PHP files from Version 6.3 recipes. I would provide both Yaml and PHP and they can use what they want. I could just think of that symfony/skeleton from 6.3 or other future version is provided with the PHP recipes endpoint and not longer with the YAML recipes endpoint.