Using PHPDoc annotations instead of PHPStan/Psalm

[mspirkov]

Many libraries and frameworks do not use PHPStan/Psalm annotations or use them very rarely (except @phpstan-type, @psalm-type etc.). Instead, they write PHPStan/Psalm types in PHPDoc annotations.

For example:

1. https://github.com/laravel/framework
2. https://github.com/PHP-DI/PHP-DI
3. https://github.com/slimphp/Slim
4. https://github.com/sebastianbergmann/phpunit
5. https://github.com/symfony/symfony (Psalm annotations are used in rare cases)
6. https://github.com/cakephp/cakephp (PHPStan annotations are used in rare cases)
   etc.

Do we want to follow the same path?

Why it's worth doing this:

1. IDEs will start working better. They will be able to suggest types in real time. At the moment, to achieve this result, I have to write PHPDoc annotations everywhere. This approach makes the code harder to read and write.
2. Since the IDEs will start to identify types better, they will start highlighting errors that were previously only detected when running PHPStan/Psalm.
3. In the framework itself, we won't have to write 3 types of annotations everywhere: PHPDoc, PHPStan, and Psalm. We won't have to worry about their consistency.

What are the arguments against:

1. The documentation generation will break. I think this is a solvable problem, and we should just improve this mechanism.
2. Some IDEs do not support PHPStan/Psalm syntax. I think this is a problem with these IDEs, and they should solve it. I also think that not many people use these IDEs. I think the benefits outweigh the drawbacks in this case.

Are there any other problems that are preventing us from doing this?

I would like to hear the opinions of others on this matter.

[terabytesoftw]

We could do it if we first added support to the extension for generating the documents.

[mspirkov]

Cool! This is it, right?
https://github.com/yiisoft/yii2-apidoc

[samdark]

Yes. Ideally, we'd like to make it a separate, independent tool for any PHP code and use it for both Yii2 and Yii3.

[samdark]

Now it's Yii2 specific.

[samdark]

I don't think it is a good idea:

1. IDEs such as PhpStorm can read Psalm and PHPStan annotations and merge these with regular types, so there should be no gain in code support in IDEs compared to what we do already.
2. Some IDEs and editors aren't able to work with these but can work well with regular types. Changing everything to just PhpStan syntax in regular @param will break these.
3. Our apidoc can process regular types only, same as phpDocumentor it is based on.

[mspirkov]

phpDocumentator itself uses PHPStan annotations in rare cases. Basically everything is written in PHPDoc annotations.

[terabytesoftw]

I can confirm that.

[terabytesoftw]

If we can update the Yii2 api-doc to use the latest version of the documenter, without breaking document generation, that would be great for version 2.2, and have a modern and clean PHPDoc.

[samdark]

I'd try to decouple api-doc from Yii2 to use it for Yii3 and any PHP code. Yii2 specific things should be extensions.

[mspirkov]

I'll try to add PHPStan/Psalm syntax support to yii2-apidoc soon, if no one minds.
I think this will be a very useful feature, especially considering that this library will be used outside of Yii2.