Discourage usage of legacy properties in WP_Network

[johnjamesjacoby]

@property's is for magic properties: ​https://phpdoc.org/docs/latest/references/phpdoc/tags/property.html

Since $id isn't magic, let's remove the @property documentation.

See: #37050

[jeremyfelt]

Indeed. It's "magic" in that string is forced to int, but not magic in that the property isn't already defined with a docblock. :+1:

[jeremyfelt]

Hmm. On second thought. Does the @property tag help in this case because the property itself is private and access is magic?

[flixos90]

@jeremyfelt Yes, that's probably the reason we put it there. The @property needs to remain there so that IDEs etc recognize this property as public.

[johnjamesjacoby]

Replying to flixos90:

@jeremyfelt Yes, that's probably the reason we put it there. The @property needs to remain there so that IDEs etc recognize this property as public.

If the concern is IDEs and documentation coverage, the current approach isn't quite right either. Now it's declared in two places: the class itself, and the docblock, and they are in conflict with each other (and my IDE complains about the overlap.)

@property is also reserved for invisible magic variables, not known ones (in this case, defined in the class object.)

Having it wrong is worse than not having it at all. I'd still vote ro remove it until we decide what is most accurate.

[johnjamesjacoby]

Replying to jeremyfelt:

Hmm. On second thought. Does the @property tag help in this case because the property itself is private and access is magic?

It really shouldn't be both privately defined & publicly magic. Either we shouldn't privately define it, or we should publicly define it as what the magic method will always return.

[flixos90]

Replying to johnjamesjacoby:

It really shouldn't be both privately defined & publicly magic. Either we shouldn't privately define it, or we should publicly define it as what the magic method will always return.

Well if PHP was type-safe... I'm not sure which solution to go for here. I tend to leave it publicly magic and change the internals. So I assume that would mean we'd need to store it in another way than the $id property?

[johnjamesjacoby]

Deprecate $blog_id, remove magic @property variables, and call __set() in __constructor() so data is cast correctly

[flixos90]

It's partly still a bug, but I think enhancement is a better fit now - which is a good thing. :)

[flixos90]

Since it's an enhancement, let's get back to it early in 4.8.

[flixos90]

Related: #38630