Docs: Add documentation for WordPress.PHP.TypeCasts #2591

brentwilson-clariio · 2025-08-26T22:09:30Z

Related to #1722

This PR adds a new documentation file:
WordPress/Docs/PHP/TypeCastsStandard.xml

What it covers

Documents the rule enforced by the WordPress.PHP.TypeCasts sniff:

Normalizes legacy float casts ((double), (real)) to (float).

Notes

Other type-cast related rules in the WordPress standard are enforced by separate sniffs:

Short form keywords ((int), (bool), (string)): PSR12.Keywords.ShortFormTypeKeywords
No spaces inside parentheses: Squiz.WhiteSpace.CastSpacing
Exactly one space after the cast: Generic.Formatting.SpaceAfterCast

…P.TypeCasts

jrfnl

@brentwilson-clariio Thanks for picking this up! I've just had a quick look and left some feedback for you to consider.

jrfnl · 2025-08-26T22:20:33Z

WordPress/Docs/PHP/TypeCastsStandard.xml

+      Note: Other type-cast rules in the WordPress standard
+      are enforced by different sniffs:
+      - Short forms like (int), (bool), (string):
+        PSR12.Keywords.ShortFormTypeKeywords
+      - No spaces inside parentheses:
+        Squiz.WhiteSpace.CastSpacing
+      - Exactly one space after the cast:
+        Generic.Formatting.SpaceAfterCast


This whole block doesn't belong here. Each sniff functions independently of other sniffs. That also means that the docs should be independent of each other and should just focus on what this sniff does.

Thanks! I’ve removed the paragraph referencing other sniffs. The docs now only describe what WordPress.PHP.TypeCasts enforces.

jrfnl · 2025-08-26T22:21:02Z

WordPress/Docs/PHP/TypeCastsStandard.xml

+    <code_comparison>
+        <code title="Invalid: legacy float casts">
+        <![CDATA[
+<?php


PHP open tag is not needed here. (Same for the "invalid" code sample)

Removed <?php from all code samples as suggested.

jrfnl · 2025-08-26T22:22:11Z

WordPress/Docs/PHP/TypeCastsStandard.xml

+<documentation title="Type Casts">
+    <standard>
+    <![CDATA[
+      This sniff normalizes float type cast keywords.


This sentence seems redundant.

Reworded the opener to be shorter and clearer. It now states the rules enforced without repeating itself.

jrfnl · 2025-08-26T22:23:17Z

WordPress/Docs/PHP/TypeCastsStandard.xml

@@ -0,0 +1,38 @@
+<?xml version="1.0"?>
+<documentation title="Type Casts">


Suggested change

<documentation title="Type Casts">

<?xml version="1.0"?>

<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"

title="Type Casts"

>

Added the schema header and xsi:noNamespaceSchemaLocation pointing to phpcsdocs.xsd.

jrfnl · 2025-08-26T22:25:42Z

WordPress/Docs/PHP/TypeCastsStandard.xml

+      Use (float) instead of legacy synonyms:
+      - Disallowed: (double), (real)
+      - Allowed:    (float)


This is incorrect/incomplete.

The sniff:

Forbids the use of non-standard casts for floats.

Forbids the use of the (unset) cast.

Discourages the use of the (binary) cast.

Considering the above, I believe the code samples also need work.

Updated the standard text and the code examples to cover all three behaviors:
• (double)/(real) → error (normalize to (float))
• (unset) → error (removed in PHP 8.0; suggest unset())
• (binary) → warning (discouraged)

jrfnl · 2025-08-26T22:29:04Z

WordPress/Docs/PHP/TypeCastsStandard.xml

+    </standard>
+
+    <code_comparison>
+        <code title="Invalid: legacy float casts">


Suggested change

<code title="Invalid: legacy float casts">

<code title="Invalid: Using legacy float casts.">

Adjusted the code block titles to your suggested wording.

jrfnl · 2025-08-26T22:29:21Z

WordPress/Docs/PHP/TypeCastsStandard.xml

+$size  = <em>(real)</em>   $value;
+        ]]>
+        </code>
+        <code title="Valid: normalized float cast">


Suggested change

<code title="Valid: normalized float cast">

<code title="Valid: Using normalized float casts.">

Adjusted the code block titles to your suggested wording.

Updated code block titles to “Valid: Using normalized float casts.” (and similar phrasing for the other examples), as suggested.

jrfnl · 2025-08-26T22:30:02Z

WordPress/Docs/PHP/TypeCastsStandard.xml

+    ]]>
+    </standard>
+
+    <code_comparison>


The code comparison should have "valid" on the left (first code sample), "invalid" on the right (second code sample).

Thanks for the feedback! I’ve reordered the code examples so that Valid is on the left and Invalid is on the right, as suggested.

…set), discourage (binary))

…t) per review

rodrigoprimo

Thanks for this PR, @brentwilson-clariio! I'm genuinely sorry for the delay to respond. There was some miscommunication and I didn't realize the WPCS maintainers were waiting for me to post a review. I will make sure to respond faster going forward.

I checked and confirmed that you addressed the points that Juliette raised. I left a few other remarks for us to discuss. Let me know what you think and if you have any questions.

Thanks again.

rodrigoprimo · 2025-10-24T17:36:11Z

WordPress/Docs/PHP/TypeCastsStandard.xml

+<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"
+    title="Type Casts"
+>


Suggested change

>

>

rodrigoprimo · 2025-10-24T17:39:34Z

WordPress/Docs/PHP/TypeCastsStandard.xml

+        </code>
+        <code title="Invalid: Using the (unset) cast.">
+        <![CDATA[
+result = <em>(unset)</em> $value;


Suggested change

result = (unset) $value;

$result = (unset) $value;

bytes below is also missing a $.

rodrigoprimo · 2025-10-24T17:57:41Z

WordPress/Docs/PHP/TypeCastsStandard.xml

+      Enforce normalized and safe type casts.
+
+      • Use (float) instead of legacy float casts.
+      • Do not use the (unset) cast. Use unset().
+      • Avoid the (binary) cast (discouraged).


Suggested change

Enforce normalized and safe type casts.

• Use (float) instead of legacy float casts.

• Do not use the (unset) cast. Use unset().

• Avoid the (binary) cast (discouraged).

Enforce normalized and safe type casts.

• Use (float) instead of legacy float casts.

• Do not use the (unset) cast. Use unset().

• Avoid the (binary) cast (discouraged).

rodrigoprimo · 2025-10-24T19:11:51Z

WordPress/Docs/PHP/TypeCastsStandard.xml

+    </code_comparison>
+
+    <code_comparison>
+        <code title="Valid: Prefer a clear alternative.">


Maybe "Valid: Using (string) cast instead."? This way the title clearly communicates what is the alternative like the other titles.

That being said, I noticed that the sniff also detects the binary string prefix notation b"string" which is also tokenized as T_BINARY_CAST, but in this case using (string) is not the correct alternative. I believe we should explicitly mention in the documentation that b"string" also trigger the sniff both here with an example and in the standard description above.

In that case, the title could be something like "Valid: (binary) is not used." or "Valid: Use (string) or regular strings."

Another option is to create a separate <code_comparison> block for the binary string. Tipically, sniff documentation uses a single <code_comparison> block per warning/error message that is triggered by the sniff. But in this case it might make sense to have a separate block.

What do you think?

rodrigoprimo · 2025-10-24T19:13:45Z

WordPress/Docs/PHP/TypeCastsStandard.xml

+    <code_comparison>
+        <code title="Valid: Prefer a clear alternative.">
+        <![CDATA[
+bytes = (string) $value;


Suggested change

bytes = (string) $value;

bytes = (string) $value;

rodrigoprimo · 2025-10-24T19:31:22Z

WordPress/Docs/PHP/TypeCastsStandard.xml

+>
+    <standard>
+    <![CDATA[
+      Enforce normalized and safe type casts.


I'm unsure about a few things in this paragraph:

Mentioning that the casts that are not recommended are not safe. Are they all really not safe? I can see why using the casts that were removed is not safe, but not all casts discouraged by the sniff were removed.

Maybe we could explicitly mention the legacy float casts?

I don't think it is necessary to mention in parenthesis that (binary) is discouraged. If we want to mention that maybe we can include it in the main sentence?

Here is a suggestion of a possible alternative for description. Feel free to create your own version.

Type casts must use normalized keywords. • Use (float) not (double) or (real). • Do not use the (unset) cast. Use unset(). • Do not use the (binary) cast or b"string" prefix. Use (string) casts or regular string literals instead.

rodrigoprimo · 2025-10-24T19:32:00Z

WordPress/Docs/PHP/TypeCastsStandard.xml

+    <code_comparison>
+        <code title="Valid: Use unset().">
+        <![CDATA[
+unset( $value );


Suggested change

unset( $value );

unset( $value );

rodrigoprimo · 2025-10-24T19:45:22Z

I just realized something else. From php.net (https://www.php.net/manual/en/language.types.type-juggling.php):

Caution
The (binary) cast and b prefix exists for forward support. Currently (binary) and (string) are identical, however this may change and should not be relied upon.

Since the manual says that there is no guarantee that (binary) and (string) will continue to be identical, I guess we should not recommend it in the documentation. Instead maybe the documentation should say that using (binary) is not recommended without providing an alternative? That may be the reason the sniff message does not recommend using (string).

jrfnl · 2025-10-24T21:12:31Z

Since the manual says that there is no guarantee that (binary) and (string) will continue to be identical, I guess we should not recommend it in the documentation. Instead maybe the documentation should say that using (binary) is not recommended without providing an alternative? That may be the reason the sniff message does not recommend using (string).

Just so you know: the (binary) cast is deprecated as of PHP 8.5 and will be removed in PHP 9.0. The suggested replacement is using (string). See: https://wiki.php.net/rfc/deprecations_php_8_5#deprecate_non-standard_cast_names

rodrigoprimo · 2025-10-27T12:43:30Z

Thanks for your input, @jrfnl. In that case, I think that @brentwilson-clariio can ignore my last comment and the documentation can mention that (string) should be used instead of (binary).

Docs: document (double|real) → (float) normalization for WordPress.PH…

4f38caf

…P.TypeCasts

jrfnl requested changes Aug 26, 2025

View reviewed changes

jrfnl added Status: Awaiting feedback Type: Documentation Component: Core labels Aug 26, 2025

jrfnl reviewed Aug 26, 2025

View reviewed changes

brentwilson-clariio added 2 commits August 26, 2025 15:39

Docs: refine TypeCasts docs per review (double/real→float, forbid (un…

795e5ff

…set), discourage (binary))

Docs: reorder TypeCasts code examples to Valid (left) / Invalid (righ…

6bf9ab7

…t) per review

brentwilson-clariio requested a review from jrfnl August 26, 2025 22:57

jrfnl removed the Status: Awaiting feedback label Aug 26, 2025

jrfnl mentioned this pull request Aug 26, 2025

Add documentation for each sniff #1722

Open

61 tasks

rodrigoprimo mentioned this pull request Sep 1, 2025

Docs: Add documentation for WordPress.Security.EscapeOutput #2585

Open

rodrigoprimo suggested changes Oct 24, 2025

View reviewed changes

rodrigoprimo mentioned this pull request Oct 24, 2025

Type cast rules in handbook incomplete - missing (double), (unset), (binary) documentation WordPress/wpcs-docs#154

Closed

		@@ -0,0 +1,38 @@
		<?xml version="1.0"?>
		<documentation title="Type Casts">

	<code title="Invalid: legacy float casts">
	<code title="Invalid: Using legacy float casts.">

	<code title="Valid: normalized float cast">
	<code title="Valid: Using normalized float casts.">

	result = <em>(unset)</em> $value;
	$result = <em>(unset)</em> $value;

Uh oh!

Docs: Add documentation for WordPress.PHP.TypeCasts #2591

Are you sure you want to change the base?

Docs: Add documentation for WordPress.PHP.TypeCasts #2591

Conversation

brentwilson-clariio commented Aug 26, 2025

What it covers

Notes

Uh oh!

jrfnl left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rodrigoprimo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rodrigoprimo commented Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jrfnl commented Oct 24, 2025

Uh oh!

rodrigoprimo commented Oct 27, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rodrigoprimo commented Oct 24, 2025 •

edited

Loading