Skip to content

[Update] Docs for array declaration spacing sniff #2593

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: develop
Choose a base branch
from
Open

[Update] Docs for array declaration spacing sniff #2593

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ac45798
Adding documentation for WordPress.Arrays.ArrayDeclarationSpacing
RafaelFunchal Sep 17, 2024
f676769
docs: Use individual <em> tags per line for better clarity
mattgaldino Aug 26, 2025
16949aa
docs: Change 'associative keys' to 'keys' for clearer terminology and
mattgaldino Aug 26, 2025
6bd80ec
docs: Add associative array example and clarify multi-line array rule
mattgaldino Aug 26, 2025
c2b316c
docs: Fix code examples to follow WordPress Coding Standards
mattgaldino Aug 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 75 additions & 0 deletions WordPress/Docs/Arrays/ArrayDeclarationSpacingStandard.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
<?xml version="1.0"?>
<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"
title="Array Declaration Spacing"
>
<standard>
<![CDATA[
When an array uses keys, each key/value pair must start on a new line.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is something else that I missed in my original review. Using the default configuration of the sniff, which is what we want to document the XML file, the error ArrayItemNoNewLine is only triggered for multi-item single-line arrays, so it might be worth including this information in the description and in the code comparison titles.

Suggested change
When an array uses keys, each key/value pair must start on a new line.
When a multi-item array uses keys, each key/value pair must start on a new line.

]]>
</standard>
<code_comparison>
<code title="Valid: There is only one key/value pair per line.">
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<code title="Valid: There is only one key/value pair per line.">
<code title="Valid: Only one key/value pair per line on a multi-item array.">

<![CDATA[
$args = array(
<em>'post_id' => 22</em>,
<em>'category' => 1</em>,
);
]]>
</code>
<code title="Invalid: More than one key/value pair per line.">
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<code title="Invalid: More than one key/value pair per line.">
<code title="Invalid: Single line multi-item array using keys.">

<![CDATA[
$args = array(
<em>'post_id' => 22, 'category' => 1</em>,
);
Comment on lines +22 to +24
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One thing that I missed in my original review is that in order for this example to trigger the AssociativeArrayFound error, which I believe is the intention of this example, everything should be in the same line. Currently, this example triggers the ArrayItemNoNewLine error that is already covered in the <standard>/<code_comparison> block below. Could you please look into that? Let me know if you need any help. You might need to adjust the example so that it fits in a single line because of the 48 characters per line limit (not counting the <em> tags).

]]>
</code>
</code_comparison>
<standard>
<![CDATA[
Each item in a multi-line array must be on a new line.
]]>
</standard>
<code_comparison>
<code title="Valid: Only one array item per line.">
<![CDATA[
$args = array(
<em>'post_id'</em>,
<em>'comment_count'</em>,
<em>'post_type'</em>,
);
]]>
</code>
<code title="Invalid: More than one item per line in a multi-line array.">
<![CDATA[
$args = array(
<em>'post_id', 'comment_count', 'post_type'</em>,
);
]]>
</code>
</code_comparison>
<standard>
<![CDATA[
Associative arrays with multiple key-value pairs must also follow this rule.
]]>
</standard>
<code_comparison>
<code title="Valid: Each key-value pair on its own line.">
<![CDATA[
$settings = array(
<em>'width' => 300</em>,
<em>'height' => 200</em>,
<em>'color' => 'blue'</em>,
);
]]>
</code>
<code title="Invalid: Multiple key-value pairs on the same line in a multi-line array.">
<![CDATA[
$settings = array(
<em>'width' => 300, 'height' => 200</em>,
<em>'color' => 'blue'</em>,
);
]]>
</code>
</code_comparison>
Comment on lines +51 to +74
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm sorry if my comment in the original PR was not clear, but in https://github.com/WordPress/WordPress-Coding-Standards/pull/2489/files#r1775277204, I was not suggesting to add a new <standard>/<code_comparison> block. I don't think this is necessary. Instead, I was suggesting adding a new valid/invalid example to the <code_comparison> block that already exists. <code_comparison> blocks can have multiple examples when needed. Or do you see a reason to have a separate <standard>/<code_comparison> block in this case?

</documentation>
Loading