Symfony-docs: Use Symfony 4.x without Flex missing docs

[ofbeaton]

Flex should be used by default, but it is still optional.
https://symfony.com/doc/current/setup/flex.html

Where are the docs for using symfony 4.x without flex? All the docs assume you are using flex and don't provide the optional part at all or mention the extra configurations needed when not using it.

So far, when trying to upgrade a 3.4 app to 4.0 without flex, I've noticed that:

• symfony-cmd is unrecognized in composer.json
• I believe config/packages/${env} isn't working for phpunit

Pages that list the flex-way should also list a non-flex way. For example https://symfony.com/doc/current/testing.html says to run composer require --dev browser-kit but this only works with flex. Without flex you need to do composer require --dev symfony/browser-kit and also add whatever flex auto-configure adds (it should list what you need to add)

Without having a lengthy discussion about why I can't use flex (symfony.sh is blocked on my gov work network of ~263,000 employees), if it is optional, the docs should support using it that way.

My https://stackoverflow.com/questions/48410209/where-are-docs-for-symfony4-without-flex went unanswered, likely because docs don't actually exist.

Asking in slack resulted in being told to create an issue for it.

[xabbuh]

Basically said, you will just update the symfony/symfony package like you did before when updating to a new version of Symfony. You could stop depending on symfony/symfony and pull in all the needed components manually, but personally I would not mess with that if you cannot use Flex because of the overhead you have to do manually that would have been done by Flex instead.

For now, you then need to ignore the additional instructions in the documentation that explain which Symfony component you need to install (because you have them all thanks to the symfony/symfony package). Maybe we could add a generic sentence to all these installation instructions that we have right now.

You can then make use of the additional config files that are used in a Flex application (basically config/packages/*), but in this case you would need to ensure that all these files are loaded in your application (you can compare the default kernel of a Flex application with your kernel class). The easier part would probably be to just place config options in the config*.yml files you are already used to. I am not sure how we could best cover this in the docs. Maybe we need a small document explaining how to read the docs if you are not using Flex?

[ofbeaton]

You say keep using symfony/symfony for the 4.x branch, and certainly the upgrade page mentions doing this "symfony/symfony": "^4.0", https://symfony.com/doc/current/setup/upgrade_major.html

However many places state that symfony/symfony cannot be used with 4.x

The symfony standard edition itself also states this on github WARNING: This distribution does not support Symfony 4. See the Installing & Setting up the Symfony Framework page to find a replacement that fits you best. https://github.com/symfony/symfony-standard

The flex page contains conflicting information If the project's composer.json file contains symfony/symfony dependency, it still depends on the Symfony Standard edition, which is no longer available in Symfony 4. First, remove this dependency: https://symfony.com/doc/current/setup/flex.html

This makes it sound like you CANNOT use symfony/symfony with 4.x even without flex.

[xabbuh]

For the Symfony Standard Edition, it just means that there is no version to start a new application with Symfony 4. However, updating an existing application from 3 to 4 is not a problem.

[ofbeaton]

If symfony 4.x is all about composition over inheritance (https://medium.com/@fabpot/fabien-potencier-4574622d6a7e), and flex is optional, shouldn't the docs support using composition without flex (not using symfony/symfony`)?

Or is composition only possible with flex? If so, and since flex is the default, I already see how most of the docs are problematic, flex is creating a divide.

If I could easily use flex without always-on access to symfony.sh my issue would be resolved, though flex is still stated as optional so that issue would still remain.

[xabbuh]

You could do that yourself of course. But that's one of the pain points you had before using Flex when trying to compose everything yourself: Enabling additional features becomes a boring and tedious task.

[theofidry]

There is actually little magic with flex, everything different happens in the default kernel class. So if you want to cherry-pick some features and see what is different you should compare your kernel to it.

[javiereguiluz]

@ofbeaton I appreciate your proposal to improve Symfony Docs. And I agree with you that is a bit "misleading" to say that you can use Symfony without Flex and then the official docs always assume that you are using Flex. However, there's two big reasons for doing that:

1) The current docs are already a bit complex because we need to explain things "when using them in a Symfony app" and "when using them in standalone components". This would add another division: "when using a Flex app" and "when not using a Flex app". That's too much for the average reader.
2) We barely have the resources to document all the new added Symfony features and to fix reported issues. I'm afraid that considering to add lots of new docs to explain things when not using Flex is unthinkable. We simply don't have the resources to do that.

I understand if this answer disappoints you but I wanted to be honest about why we must close this without fixing it. I'm sorry.

[ofbeaton]

Thanks for the honesty @javiereguiluz. I really appreciate it.

[gnat42]

Just thought I'd add a small update as I came here when upgrading a project from 3.4.x to 4.2.x. I managed to get everything updated and tests passing but had issues because of the new directories being created prematurely etc. Eventually I managed to get it updated without flex. The last issues I faced was that the DistributionBundle is gone so composer.json events had issues. Copying over that part of a 4.x project requires flex to run the symfony-cmd pieces.

There's nothing that seems to provide it, DistributionBundle doesn't support sf 4. So although you don't need flex you kinda do. I replaced that section in composer.json with this

  "scripts": {
    "symfony-scripts": [
      "Incenteev\\ParameterHandler\\ScriptHandler::buildParameters",
      "bin/console cache:clear --no-warmup",
      "bin/console assets:install web"
    ],
    "post-install-cmd": [
      "@symfony-scripts"
    ],
    "post-update-cmd": [
      "@symfony-scripts"
    ]
  },

which seems to do most of what it needs to. Eventually I'll also add flex but in the meantime I thought I'd report back so google searches find at least a little info.