Skip to content

[Update] Documentation for sniff WordPress.Files.FilesName #2590

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 6 commits into
base: develop
Choose a base branch
from
Open

[Update] Documentation for sniff WordPress.Files.FilesName #2590

Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
6d1f6bb
Add: documentation for FileName sniff
Nic-Sevic Sep 17, 2024
4f4f541
fix: syntax issues
Nic-Sevic Sep 17, 2024
a08e092
initial edits, breaking up standards
jasonkenison Aug 26, 2025
68a2773
updated examples, added new mimetype examples
jasonkenison Aug 26, 2025
200cdfa
clarified code examples and standard text
jasonkenison Sep 2, 2025
768e4a9
updated for spelling in broken "some" word
jasonkenison Sep 2, 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
86 changes: 86 additions & 0 deletions WordPress/Docs/Files/FileNameStandard.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
<?xml version="1.0"?>
<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"
title="File Name Standards"
Copy link
Collaborator

Choose a reason for hiding this comment

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

The title of the document should match the sniff name.

Suggested change
title="File Name Standards"
title="File Name"

>
<standard>
<![CDATA[
File name must not be a mimetype sublevel only file names, such as `plain.php`.
]]>
</standard>
<code_comparison>
<code title="Valid: Is not a mimetype only file name.">
<![CDATA[
<em>taxonomy-term</em>.inc
<em>class-test-sample</em>.php
<em>other-punctuation</em>.inc
]]>
</code>
<code title="Invalid: Is a mimetype only file name.">
<![CDATA[
<em>text-plain</em>.php
<em>html</em>.inc
<em>richtext</em>.php
]]>
</code>
</code_comparison>
Copy link
Collaborator

Choose a reason for hiding this comment

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

Please correct me if I'm mistaken, but I don't think the sniff has this rule.

This can be tested using one of the invalid examples provided here to see that it does not trigger an error:

$ vendor/bin/phpcs -s --standard=WordPress --sniffs=WordPress.Files.FileName text-plain.php
$

Copy link
Author

Choose a reason for hiding this comment

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

@rodrigoprimo my mistake. The THEME_EXCEPTIONS regex comment on line 43 seemed to indicate it would "not allow for mimetype sublevel only file names". I'll remove it.

Copy link
Collaborator

Choose a reason for hiding this comment

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

No worries.

I believe this regex is only used to allow for some exceptions when checking theme files when $is_theme is set to true. Since the default value of this property is false, we don't need to document it here. The convention is to document only the default behavior of the sniff.

I believe this should change, and we should include the non-default behavior as well, but that is a separate discussion (just mentioning it to give you more context).

<standard>
<![CDATA[
Filenames should be all lowercase with hyphens separating words. If `$is_theme` property is set to `true` certain theme specific exceptions are made for underscores.
Copy link
Collaborator

Choose a reason for hiding this comment

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

This is something that needs to be improved in how sniffs are documented, but currently we only mention the default behavior of the sniff, so I don't think we should mention what happens in $is_theme is set to true. Also, there should be four spaces at the start of this line.

Suggested change
Filenames should be all lowercase with hyphens separating words. If `$is_theme` property is set to `true` certain theme specific exceptions are made for underscores.
Filenames should be all lowercase with hyphens separating words.

]]>
</standard>
<code_comparison>
<code title="Valid: Lowercase and `-` separators.">
<![CDATA[
taxonomy<em>-</em>my<em>-</em>term.inc
<em>s</em>ome<em>f</em>ile.inc
Copy link
Collaborator

Choose a reason for hiding this comment

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

Considering the invalid example related to this one, I believe the valid example should separate the two words with a hyphen, no? This would also fix the error in CI that is a false positive in my opinion, as ome is incorrectly being flagged as a typo.

Suggested change
<em>s</em>ome<em>f</em>ile.inc
some<em>-</em>file.inc

Copy link
Author

Choose a reason for hiding this comment

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

@rodrigoprimo these were tricky, was trying to highlight where non-lowercase letters were used. To get past the spelling error, it now highlights <em>Some</em> as a complete word instead of just the character.

Copy link
Collaborator

Choose a reason for hiding this comment

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

For the first two errors, as they check if the whole name matches what is expect, maybe we can highlight the full name (excluding the period and the file extension)?

For the third error, I think it is better to highlight just -template as it is already the case.

<em>class</em>-testsample.inc
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 not sure if I understand this specific example. Why is class highlighted, considering that this specific error (NotHyphenatedLowercase) does not check for the class prefix? If this example does not add anything that is not already covered in the other examples, maybe it can be removed together with the corresponding invalid example?

other<em>-</em>punctuation.inc
]]>
</code>
<code title="Invalid: Other punctuation or mixed case.">
<![CDATA[
taxonomy-my<em>_</em>term.inc
<em>S</em>ome<em>F</em>ile.inc
<em>testsample</em>-Unit2.inc
other<em>+</em>punctuation<em>#</em>.inc
]]>
</code>
</code_comparison>
<standard>
<![CDATA[
Class file names should be based on the class name with `class-` prepended.
]]>
</standard>
<code_comparison>
<code title="Valid: File name matches prefix and class.">
<![CDATA[
<em>class-bulkupdater</em>.php
Copy link
Collaborator

Choose a reason for hiding this comment

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

It depends on the class name, but considering that the idea is to separate words using hyphens and also considering the name of the corresponding invalid example, maybe this one should be class-bulk-updater.php?

Related to the above, maybe you can add a code comment with the class name to those examples? And then include an example where the name is invalid because the file name does not match the class name, despite it following the other formatting rules?

Then it might also make sense to include a valid example for each of the invalid examples. Maybe there should be one invalid example without the class- prefix and one where the file name is not based on the class name? Maybe there is value to add more that I'm missing.

Copy link
Author

Choose a reason for hiding this comment

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

@rodrigoprimo might be unrelated to this sniff, but if a class is called "BulkUpdater" this would still include a '-' in the filename? Updated as requested, but can make adjustments as needed.

Examples elsewhere in wp-includes, showing 3 instances where these code standard rules aren't followed:

  • class-phppass.php contains class "PasswordHash" (does not match filename)
  • class-avif-info.php contains class "Avifinfo" (not camel cased)
  • class-walker-category-dropdown.php contains class "Walker_CategoryDropdown" (underscore in class)

Copy link
Collaborator

Choose a reason for hiding this comment

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

@rodrigoprimo might be unrelated to this sniff, but if a class is called "BulkUpdater" this would still include a '-' in the filename? Updated as requested, but can make adjustments as needed.

@jasonkenison, good question. If the class is called BulkUpdater, the expected file name is class-bulkupdater.php (without the hyphen). I suggested including the hyphen because the corresponding invalid example already has a hyphen separating bulk and updater. Adding a code comment with the class name, as suggested, should also help clarify this. This is more or less what I have in mind:

<em>class-bulk-updater</em>.php // For a class named `Bulk_Updater`.

You can run PHPCS to test it. For example, given the following file named class-bulk-updater.php:

<?php

class BulkUpdater {}

We get the following error when running this sniff:

vendor/bin/phpcs -s --standard=WordPress --sniffs=WordPress.Files.FileName class-bulk-updater.php 

FILE: class-bulk-updater.php
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 1 | ERROR | Class file names should be based on the class name with "class-" prepended. Expected class-bulkupdater.php, but found class-bulk-updater.php. (WordPress.Files.FileName.InvalidClassFileName)
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Time: 107ms; Memory: 12MB

Examples elsewhere in wp-includes, showing 3 instances where these code standard rules aren't followed:

I was unable to find class-phppass.php in the WP repository. WP excludes the file class-avif-info.php from the PHPCS checks (https://github.com/WordPress/wordpress-develop/blob/1139a51e9c6608dc235938d9d234ed185c5d5706/phpcs.xml.dist#L55). class-walker-category-dropdown.php does trigger a warning (it is a warning and not an error because WP changes the configuration of this particular sniff: https://github.com/WordPress/wordpress-develop/blob/1139a51e9c6608dc235938d9d234ed185c5d5706/phpcs.xml.dist#L140-L142):

$ ./vendor/squizlabs/php_codesniffer/bin/phpcs ./src/wp-includes/class-walker-category-dropdown.php                                      
W 1 / 1 (100%)



FILE: src/wp-includes/class-walker-category-dropdown.php
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
FOUND 0 ERRORS AND 1 WARNING AFFECTING 1 LINE
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 1 | WARNING | Class file names should be based on the class name with "class-" prepended. Expected class-walker-categorydropdown.php, but found class-walker-category-dropdown.php. (WordPress.Files.FileName.InvalidClassFileName)
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Time: 476ms; Memory: 134MB

]]>
</code>
<code title="Invalid: File name missing prefix or class.">
<![CDATA[
<em>class.</em>bulk-updater.php
Copy link
Collaborator

Choose a reason for hiding this comment

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

I wonder if here it is not better to highlight just the dot as this is the exact part that would cause the error?

Suggested change
<em>class.</em>bulk-updater.php
class<em>.</em>bulk-updater.php

<em>bulkupdater-class</em>.php
class-<em>CustomFormatter</em>.php
]]>
</code>
</code_comparison>
<standard>
<![CDATA[
Files in `wp-includes` containing template tags should end in `-template`.
Copy link
Collaborator

Choose a reason for hiding this comment

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

I believe this description could detail a bit more which files in the wp-includes directory should end in -template. What do you think of the suggestion below? Feel free to improve it or create something different (note that this line should start with four spaces and not three).

Suggested change
Files in `wp-includes` containing template tags should end in `-template`.
Non-class files in the directory `wp-includes` with a "@subpackage Template" tag should use the `-template` suffix.

]]>
</standard>
<code_comparison>
<code title="Valid: File name with proper prefix/suffix.">
Copy link
Collaborator

Choose a reason for hiding this comment

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

Maybe remove prefix here and in the title below as this particular error is checking just for the suffix of the file and not a prefix?

<![CDATA[
general<em>-template</em>.php
]]>
</code>
<code title="Invalid: File name missing prefix/suffix.">
<![CDATA[
<em>general</em>.php
]]>
</code>
</code_comparison>
</documentation>
Loading