Skip to content

Add support for Enums to filename sniff #170

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

Merged
merged 2 commits into from
Mar 17, 2025
Merged

Add support for Enums to filename sniff #170

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a9f4641
Add support for Enums to filename sniff
jaymcp Mar 10, 2025
5fed4ec
Add missing documentation
jaymcp Mar 10, 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
3 changes: 2 additions & 1 deletion BigBite/Docs/Files/FileNameStandard.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,12 @@
<documentation title="File Names">
<standard>
<![CDATA[
Files containing classes, interfaces, or traits should be prefixed appropriately - prefixed with the type, and then lower-kebab-case matching the name of the type. Examples:
Files containing classes, interfaces, traits, or enums should be prefixed appropriately - prefixed with the type, and then lower-kebab-case matching the name of the type. Examples:
- trait My_Trait {} => trait-my-trait.php
- interface My_Interface {} => interface-my-interface.php
- class My_Class {} => class-my-class.php
- abstract class My_Abstract_Class {} => abstract-class-my-abstract-class.php
- enum My_Enum {} => enum-my-enum.php
]]>
</standard>
</documentation>
62 changes: 26 additions & 36 deletions BigBite/Sniffs/Files/FileNameSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -158,6 +158,12 @@ public function process_token( $stack_ptr ) {
$trait_ptr = $this->phpcsFile->findNext( \T_TRAIT, $stack_ptr );
$interface_ptr = $this->phpcsFile->findNext( \T_INTERFACE, $stack_ptr );

$enum_ptr = false;
// Since PHP 8.1.
if ( defined( '\T_ENUM' ) ) {
$enum_ptr = $this->phpcsFile->findNext( \T_ENUM, $stack_ptr );
}

if ( false !== $class_ptr && $this->is_test_class( $this->phpcsFile, $class_ptr ) ) {
/*
* This rule should not be applied to test classes (at all).
Expand All @@ -173,7 +179,7 @@ public function process_token( $stack_ptr ) {
$file_name = basename( $file );

// plain file, just check hyphenation.
if ( ! $class_ptr && ! $trait_ptr && ! $interface_ptr ) {
if ( ! $class_ptr && ! $trait_ptr && ! $interface_ptr && ! $enum_ptr ) {
$this->check_filename_is_hyphenated( $file_name );
return ( $this->phpcsFile->numTokens + 1 );
}
Expand Down Expand Up @@ -202,10 +208,10 @@ public function process_token( $stack_ptr ) {
return ( $this->phpcsFile->numTokens + 1 );
}

$is_wpinc_path = false !== strpos( $file, \DIRECTORY_SEPARATOR . 'wp-includes' . \DIRECTORY_SEPARATOR );

if ( $is_wpinc_path && false === $class_ptr ) {
$this->check_filename_for_template_suffix( $stack_ptr, $file_name );
// check for "enum-" prefix.
if ( false !== $enum_ptr ) {
$this->check_filename_has_enum_prefix( $enum_ptr, $file_name );
return ( $this->phpcsFile->numTokens + 1 );
}

// Only run this sniff once per file, no need to run it again.
Expand Down Expand Up @@ -365,43 +371,27 @@ protected function check_filename_has_interface_prefix( $interface_ptr, $file_na
}

/**
* Check non-class files in "wp-includes" with a "@subpackage Template" tag for a "-template" suffix.
*
* @since 3.0.0
* Check files containing an enum for the "enum-" prefix,
* and that the rest of the file name reflects the enum name.
*
* @param int $stackPtr Stack pointer to the first PHP open tag in the file.
* @param string $file_name The name of the current file.
* @param mixed $enum_ptr the token stack.
* @param string $file_name the name of the file.
*
* @return void
* @return bool
*/
protected function check_filename_for_template_suffix( $stackPtr, $file_name ) {
$subpackage_tag = $this->phpcsFile->findNext( \T_DOC_COMMENT_TAG, $stackPtr, null, false, '@subpackage' );
if ( false === $subpackage_tag ) {
return;
}
protected function check_filename_has_enum_prefix( $enum_ptr, $file_name ) {
$extension = strrchr( $file_name, '.' );
$enum_name = ObjectDeclarations::getName( $this->phpcsFile, $enum_ptr );
$expected = 'enum-' . $this->kebab( $enum_name ) . $extension;
$err_message = 'Enum file names should be based on the enum name with "enum-" prepended. Expected %s, but found %s.';

$subpackage = $this->phpcsFile->findNext( \T_DOC_COMMENT_STRING, $subpackage_tag );
if ( false === $subpackage ) {
return;
if ( $file_name === $expected ) {
return true;
}

$fileName_end = substr( $file_name, -13 );

if ( ( 'Template' === trim( $this->tokens[ $subpackage ]['content'] )
&& $this->tokens[ $subpackage_tag ]['line'] === $this->tokens[ $subpackage ]['line'] )
&& ( ( ! \defined( '\PHP_CODESNIFFER_IN_TESTS' ) && '-template.php' !== $fileName_end )
|| ( \defined( '\PHP_CODESNIFFER_IN_TESTS' ) && '-template.inc' !== $fileName_end ) )
) {
$this->phpcsFile->addError(
'Files containing template tags should have "-template" appended to the end of the file name. Expected %s, but found %s.',
0,
'InvalidTemplateTagFileName',
array(
substr( $file_name, 0, -4 ) . '-template.php',
$file_name,
)
);
}
$this->phpcsFile->addError( $err_message, 0, 'InvalidEnumFileName', array( $expected, $file_name ) );

return false;
}

/**
Expand Down
3 changes: 3 additions & 0 deletions BigBite/Tests/Files/FileNameUnitTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,8 @@ final class FileNameUnitTest extends AbstractSniffUnitTest {
'ClassMyClass.inc' => 1,
'InterfaceMyInterface.inc' => 1,
'TraitMyTrait.inc' => 1,
'enum-different-enum.inc' => 1,
'EnumMyEnum.inc' => 1,

// Theme specific exceptions in a non-theme context.
'single-my_post_type.inc' => 1,
Expand All @@ -62,6 +64,7 @@ final class FileNameUnitTest extends AbstractSniffUnitTest {
'ClassNonStrictClass.inc' => 1,
'InterfaceNonStrictClass.inc' => 1,
'TraitNonStrictClass.inc' => 1,
'EnumNonStrictEnum.inc' => 1,

/*
* In /FileNameUnitTests/PHPCSAnnotations.
Expand Down
3 changes: 3 additions & 0 deletions BigBite/Tests/Files/FileNameUnitTests/EnumMyEnum.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
<?php

enum My_Enum {}
8 changes: 8 additions & 0 deletions BigBite/Tests/Files/FileNameUnitTests/NonStrictClassNames/EnumNonStrictEnum.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
<!-- Annotation has to be on the second line as errors are thrown on line 1 and errors on annotation lines are ignored. -->
phpcs:set BigBite.Files.FileName strict_file_names false

<?php

enum Non_Strict_Enum {}

// phpcs:set BigBite.Files.FileName strict_file_names true
8 changes: 8 additions & 0 deletions BigBite/Tests/Files/FileNameUnitTests/NonStrictClassNames/non-strict-enum.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
<!-- Annotation has to be on the second line as errors are thrown on line 1 and errors on annotation lines are ignored. -->
phpcs:set BigBite.Files.FileName strict_file_names false

<?php

enum Non_Strict_Enum {}

// phpcs:set BigBite.Files.FileName strict_file_names true
3 changes: 3 additions & 0 deletions BigBite/Tests/Files/FileNameUnitTests/enum-different-enum.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
<?php

enum Not_My_Enum {}
3 changes: 3 additions & 0 deletions BigBite/Tests/Files/FileNameUnitTests/enum-my-enum.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
<?php

enum My_Enum {}