search

php / php-src

The PHP Interpreter
https://www.php.net
Other
38.16k stars 7.75k forks source link

Stubs: internally modifyable properties are not @readonly #15553

Open cmb69 opened 2 months ago

cmb69 commented 2 months ago

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 commented 2 months ago

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 commented 2 months ago

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

nielsdos commented 2 months ago

@property-read seems fine.

nielsdos commented 2 months ago

cc @kocsismate

kocsismate commented 2 months ago

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 commented 2 months ago

@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.