Support @readonly phpdoc

[herndlm]

Same as psalm does it, see https://psalm.dev/docs/annotating_code/supported_annotations/#psalm-readonly-and-readonly

I guess this would be very useful for pre PHP 8.1 and/or to safely enable native readonly. But I think this is also the first step in the direction of a @phpstan-immutable phpdoc on class level, but that's a different thing.

If I understood things right this should not interfere with some of the other rules that are related to native readonly because the phpdoc is not used in https://github.com/phpstan/phpstan-src/blob/1.6.7/src/Node/ClassPropertyNode.php#L77. I added tests to check that where it made sense to me. irrelevant, because the phpdoc rules were separated later on :)

Refs: phpstan/phpstan#4082

[staabm]

I had a discussion in the past about implementing it.

These are the main directions, which ondrey gave me:

My thinking is that there are separate rules: for uninitialized properties that are opt-in with a config option
for native readonly properties checked on PHP 8.1+
and a different (but similar) rule would have to be added for
@readonly PHPDoc properties.
but it's less relevant over time as people upgrade their PHP version and can start using the native feature.
if you look at UninitializedPropertyRule + ReadOnlyPropertyAssignRule + MissingReadOnlyPropertyAssignRule you can see the differences and the similarilties

I don't know whether this information is still valid as is... just to let you know.

[ondrejmirtes]

I think for this to work, we need a new method PhpPropertyReflection::isReadOnlyByPhpDoc() and PHPStan\Node\ClassPropertyNode::isReadOnlyByPhpDoc() and a new set of rules (or modified implementation of the current ones with a new set of tests):

• UninitializedPropertyRule
• MissingReadOnlyPropertyAssignRule
• ReadOnlyPropertyAssignRefRule
• ReadOnlyPropertyAssignRule

I really want to separate the rules for "this is native readonly keyword" and "this is done by PHPDoc" as they can diverge over time. I don't want the current isReadOnly() methods to also report true for PHPDocs.

[herndlm]

I separated native and phpdoc readonly, as requested, and for simplicity I chose to adapt the current existing rules. I also added new test sets that are basically duplicates of the current ones minus PHP 7.4+ features (native property types, native readonly, enums).

Good idea with the separation for sure, see #1295 (comment) where I decided to not add phpdoc readonly support for MissingReadOnlyPropertyAssignRule and UninitializedPropertyRule because things start to get mixed up with native readonly. I could add support back without that weird change, it would only work combined with native type hints if I'm not mistaken. Maybe that's fine after all. I can't decide :)

What do you think, is this going in the right direction?

[herndlm]

Sorry for my impatience, I hate that xD
But since I see the 1.7 release nicely finishing up - do you think this can still be squeezed in? I'll prioritize any requested changes

[ondrejmirtes]

do you think this can still be squeezed in? I'll prioritize any requested changes

Let me assure you that you can keep calm because it mostly doesn't matter :)

• No one says that PHPStan 1.8.0 cannot be released like 5 days after 1.7.0 :)
• No one says that this PR cannot be released in 1.7.1 for example :)

[ondrejmirtes]

where I decided to not add phpdoc readonly support for MissingReadOnlyPropertyAssignRule and UninitializedPropertyRule

With my proposal of separate rules, this should probably be done, right?

[ondrejmirtes]

Really nice! Almost there :)

[ondrejmirtes]

Thank you!

[ondrejmirtes]

Can you please send an update to this page @herndlm? https://phpstan.org/writing-php-code/phpdocs-basics

Thank you!

[herndlm]

I'll update the docs tomorrow, have fun in Verona!