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

jasonkenison · 2025-08-26T22:02:14Z

Related to #1722
Continuing updates from #2492

Grouped all checks into individual standards.
Included additional standards not previously included
Added more check valid and invalid examples

rodrigoprimo

Thanks for working on this PR, @jasonkenison! I left some comments with suggestions. Let me know if you have any questions.

rodrigoprimo · 2025-09-02T17:10:20Z

WordPress/Docs/Files/FileNameStandard.xml

+    </code_comparison>
+    <standard>
+    <![CDATA[
+   Files in `wp-includes` containing template tags should end in `-template`.


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.

rodrigoprimo · 2025-09-02T17:17:44Z

WordPress/Docs/Files/FileNameStandard.xml

+<?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"


The title of the document should match the sniff name.

Suggested change

title="File Name Standards"

title="File Name"

rodrigoprimo · 2025-09-02T17:29:12Z

WordPress/Docs/Files/FileNameStandard.xml

+    <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>


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 $

@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.

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).

rodrigoprimo · 2025-09-02T17:32:26Z

WordPress/Docs/Files/FileNameStandard.xml

+    </code_comparison>
+    <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.


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.

rodrigoprimo · 2025-09-02T17:43:03Z

WordPress/Docs/Files/FileNameStandard.xml

+        <code title="Valid: Lowercase and `-` separators.">
+        <![CDATA[
+taxonomy<em>-</em>my<em>-</em>term.inc
+<em>s</em>ome<em>f</em>ile.inc


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

somefile.inc

some-file.inc

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

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.

rodrigoprimo · 2025-09-02T17:50:35Z

WordPress/Docs/Files/FileNameStandard.xml

+        <![CDATA[
+taxonomy<em>-</em>my<em>-</em>term.inc
+<em>s</em>ome<em>f</em>ile.inc
+<em>class</em>-testsample.inc


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?

rodrigoprimo · 2025-09-02T17:59:01Z

WordPress/Docs/Files/FileNameStandard.xml

+    <code_comparison>
+        <code title="Valid: File name matches prefix and class.">
+        <![CDATA[
+<em>class-bulkupdater</em>.php


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.

@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)

@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:

class-bulk-updater.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

rodrigoprimo · 2025-09-02T18:04:40Z

WordPress/Docs/Files/FileNameStandard.xml

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


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

class.bulk-updater.php

class.bulk-updater.php

rodrigoprimo · 2025-09-02T18:14:19Z

WordPress/Docs/Files/FileNameStandard.xml

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


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?

Nic-Sevic and others added 4 commits September 17, 2024 14:52

Add: documentation for FileName sniff

6d1f6bb

fix: syntax issues

4f4f541

initial edits, breaking up standards

a08e092

updated examples, added new mimetype examples

68a2773

rodrigoprimo added Type: Documentation Component: Core labels Aug 26, 2025

jrfnl changed the title ~~Docs/word press/files/file name standard~~ [Update] Documentation for sniff WordPress.Files.FilesName Aug 26, 2025

jrfnl mentioned this pull request Aug 26, 2025

Add documentation for each sniff #1722

Open

61 tasks

rodrigoprimo suggested changes Sep 2, 2025

View reviewed changes

rodrigoprimo added the Status: Awaiting feedback label Sep 2, 2025

jasonkenison added 2 commits September 2, 2025 13:57

clarified code examples and standard text

200cdfa

updated for spelling in broken "some" word

768e4a9

	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.

	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.

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

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

Uh oh!

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

Are you sure you want to change the base?

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

Conversation

jasonkenison commented Aug 26, 2025 • edited by jrfnl Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

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!

Uh oh!

jasonkenison commented Aug 26, 2025 •

edited by jrfnl

Loading