Stubs: internally modifyable properties are not @readonly

[cmb69]

Description

We have a couple of internal classes (e.g. mysqli) which implement properties basically as hooks (i.e. internally calling a function). Such properties should not be tagged as @readonly in the stubs, because their behavior is not what users expect (their value is not fixed), and it also can be very confusing regarding the behavior of ReflectionProperty::isReadOnly() et. al, see #15309.

While at least for me this is more of a documentation issue, since the classsynopses are generated from the stub files, some improvements would need to be done there at first.

PHP Version

PHP 8

Operating System

any

[nielsdos]

I suppose the proper way to go about this is migrate those properties to a new attribute, e.g. @getter which renders the property as a hook, e.g. public Foo $prop { get; }.

[cmb69]

That's fine with me, but maybe we should use @property-read (or would that be too confusing wrt ::__get())?

[nielsdos]

@property-read seems fine.

[nielsdos]

cc @kocsismate

[kocsismate]

Yes, I'm also fine with @property-read :) Although I'm wondering whether the @calculated annotation would be fine? Can we call these properties calculated?

BTW thanks for pinging me ^^

[cmb69]

@property-read has been tradionally used by tooling (PHPDocumentor, PHPStan, Psalm and likely others; maybe there's even a FIG standard specifying that) to annotate magic __get() properties. And that is close to property hook getters, so I think it's a good idea to stick with it, so userland developers reading (and editing) stub files may understand the meaning.