Install documentation misses recommended "tools/php-cs-fixer" dir method

[cweiske]

Problem description

The README states:

The recommended way to install PHP CS Fixer is to use Composer in a dedicated composer.json file in your project, for example in the tools/php-cs-fixer directory:

But the separate installation documentation does not say anything about that: https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/blob/master/doc/installation.rst

The "recommended way" was added to the README in 1d01692.

Minimal reproducer

Compare https://github.com/PHP-CS-Fixer/PHP-CS-Fixer?tab=readme-ov-file#installation with https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/blob/master/doc/installation.rst

Fixer version

v3.57.1

PHP version

8.2

How do you run Fixer?

Composer package

Contribution Checks

• I have verified if this problem was already reported
• I am familiar with "Feature or bug?"

[Wirone]

The recommended way is mentioned in the readme and the example of how to do it is shown right below. Then you have:

For more details and other installation methods, see installation instructions.

The separate page lists alternative installation methods, so from the readme (and main docs) point of view it's correct. But if you land directly on installation instructions it in fact misses the recommended installation, so probably we should add it there too.

Do you want to update the installation docs?

[cweiske]

No, I don't want to update the installation docs.

[JParkinson1991]

Can I suggest that we add some rationale to this recommendation in the docs.

Im new to this project and opted to not go with the recommendation as there no clear reason or guidance as to why I should be.

[Wirone]

@JParkinson1991 the rationale behind it is that your dev tools should not affect your production dependencies. Yes, you can add it to require-dev and in most cases you will get desired outcome, but the more complex your project is, the bigger chance that Fixer's requirements collide with yours (and Composer is not able to resolve set of deps). It is true only for Fixer installed as a package, shim version does not have this limitation. But I agree it's not that obvious and it would be better to describe it in the docs 🙂.

[julienfalque]

This also works the other way around by the way: production dependencies should not affect dev tools. Every two years, we receive requests to make PHP CS Fixer compatible with the new major version of Symfony. This creates an unnecessary burden on us. We should be free to upgrade Symfony components we depend on whenever we feel the need to, not when one wants to update their app.