Type cast rules in handbook incomplete - missing (double), (unset), (binary) documentation

[rodrigoprimo]

While reviewing PR #2591 which adds documentation for the WordPress.PHP.TypeCasts sniff, I noticed that https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#space-usage doesn't fully document all the rules that the WordPress.PHP.TypeCasts sniff enforces in the paragraph about type casts.

The handbook currently documents:

• Type casts must be lowercase (enforced by another sniff).
• Use (int) not (integer).
• Use (bool) not (boolean).
• Use (float) not (real).

But the WordPress.PHP.TypeCasts sniff also enforces the following rules:

• Use (float) instead of (double).
• (unset) is forbidden.
• (binary) and b"string" prefix are discouraged.

When the sniff was introduced in 2018 via PR WordPress/WordPress-Coding-Standards#1483, I believe the intention was to mention (unset) and (binary) in the handbook (see WordPress/WordPress-Coding-Standards#1481 (comment) and WordPress/WordPress-Coding-Standards#1481 (comment)), but it seems that never happened or at least I was not able to find it searching the history of https://github.com/WordPress/wpcs-docs/blame/master/wordpress-coding-standards/php.md.

(double) is not mentioned in the issue discussion, but to me, since 4361cec added a explicit mention to (real), I think (double) should be mentioned as well.

Should the handbook be updated or is there a reason that I'm missing not to update it? Also, please let me know if this is not the correct repository to ask this question.

[jrfnl]

(unset) doesn't exist in PHP anymore and (binary) is deprecated as of PHP 8.5. Let's not give people any ideas please.

[jrfnl]

Oh and for the record, (real) was deprecated in PHP 7.4 and removed in PHP 8.0 and (double) is deprecated per PHP 8.5 and will be removed in PHP 9.0.

Basically the sniff already anticipated the direction PHP would go into and I don't think educating people about PHP features which are deprecated/removed is helpful in a coding style guide.

[jrfnl]

If anything, we should simplify the text once PHP 9.0 is released to remove the mention of anything but the remaining canonical casts.

[GaryJones]

I don't think educating people about PHP features which are deprecated

I think I disagree here. If I'm a regular developer, writing plugins for PHP ~8.2, and am not fully aware of what changes there are coming in 8.5, then it would be very handy for a coding standard I'm following to point out that I shouldn't use X because a future / later version of PHP has it deprecated or removed, so I don't introduce it now and have to fix it again later.

I don't believe a section of type casts people shouldn't use (where not already removed before the lowest supported PHP version for WP) would have any disadvantages. It's not giving people ideas - it's bringing clarity to what should or shouldn't be used.

[rodrigoprimo]

Thanks for the feedback, @jrfnl. I don't have the historical context of what goes into the handbook, so I may be missing something here. That being said, I agree with @GaryJones that it makes sense to document in the handbook what type casts shouldn't be used when they're still available in PHP versions WordPress supports.

[jrfnl]

I fundamentally disagree. A coding standards guide should be about coding standards, not about how to write PHP cross-version compatible code. That's what the PHP migration guides are for (and in the past the blog posts I contributed to for Make about new PHP versions).

If you look at the text of the guide as it is now, for the most part, the text is written to specify how code should be written, not how it should not be written (with only a few exceptions).
In the examples, correct and incorrect is shown at times, but the "incorrect" is rarely made explicit in the textual part.

As for PHP information: for PHP features not available in the oldest WP supported PHP version we do provide guidelines and include a warning about (not) using these features for WP Core, but there are only two places where we mention PHP deprecations (type casts + create_function) and, to be honest, for type casts this should be removed in my opinion as there was never any reason not to use the non-canonical type casts in the first place.

As for create_function - the mention of deprecation here is historical as prior to PHP 5.3, closures didn't exist and people often used create_function for quick & dirty hook-ins to WP. Considering it is also a security risk, I'm okay with leaving that mention in place until the minimum PHP version of WP has been raised to PHP 8.0, by which point mentioning create_function becomes redundant.

So, for the type cast section, I would propose to update the text to:

- [Type casts](https://www.php.net/manual/en/language.types.type-juggling.php#language.types.typecasting) must be lowercase. Always prefer the short form of type casts, (int) instead of (integer) and (bool) rather than (boolean). For float casts use (float), not (real) which is [deprecated](https://www.php.net/manual/en/migration74.deprecated.php#migration74.deprecated.core.real) in PHP 7.4, and removed in PHP 8:
+ [Type casts](https://www.php.net/manual/en/language.types.type-juggling.php#language.types.typecasting) must be lowercase. Always prefer the short, canonical form of type casts, (int) instead of (integer) and (bool) rather than (boolean). For float casts use (float).

If you like, we could update the example code like so:

- foreach ( (array) $foo as $bar ) { ...
- 
- $foo = (bool) $bar;
+ $foo = (bool) $bar; // Correct
+ $foo = (boolean) $bar; // Incorrect.

Adding information about deprecated PHP features to the coding standards guidelines would open the flood gates to adding PHPCompatibility sniffs to WPCS, which I don't think is the right move.

[rodrigoprimo]

Thanks for the additional context and information, @jrfnl. I agree with your suggestion both for updating the text and the code example. I see that @GaryJones agrees as well. Could you create a PR or do you prefer that I do it (giving you the credits)?

[jrfnl]

@rodrigoprimo Feel free to PR this.