Suppressing PHPCS Warnings for Multi-Class Files
When your project structure forces you to combine a production class and its corresponding test in a single fileâoften seen in unit testing scenarios like TestMyClass.phpâPHP Code Sniffer (PHPCS) will flag an error. The specific message is usually that "each class must be in a file by itself." While PHPCS defaults to strict adherence to PSR-12 and other coding standards, this rule assumes a separation of concerns between implementation and testing logic.
To resolve this without refactoring your entire codebase into dozens of tiny files, you can suppress the specific warning using inline comments. This approach allows you to maintain your current directory structure while keeping your linter happy.
The Suppression Syntax
PHPCS handles suppression via special comment tokens placed immediately before the problematic construct. For the "each class must be in a file by itself" error, the standard violation code is Generic.Files.OneClassPerFile.
You should place the suppression comment directly above the second class definition. Since your first class (MyClassImpl) likely doesn't violate this rule (assuming it's the only one intended for that file), you don't need to suppress anything there.
Here is how the code looks with the necessary modification:
class MyClassImpl implements MyInterface
{
// ... implementation details
}
// phpcs:ignore Generic.Files.OneClassPerFile
class MyClassTest extends \PHPUnit_Framework_TestCase
{
// ... test logic
}
The phpcs:ignore directive tells the scanner to skip the specific rule for the line that follows. By targeting the second class, you acknowledge that the first part of the file adheres to the standard while explicitly exempting the test class from the "single class per file" constraint.
Alternative Suppression Methods
If you prefer a different style or are working with an older version of PHPCS, you might see variations like // phpcs:todo or using the @phpcs-ignore syntax if you are dealing with PSR12 rules specifically. However, the modern inline format (// phpcs:ignore) is preferred in recent versions because it allows for granular control without cluttering the codebase with long directives.
You can also suppress the entire block of code following the comment by adding a colon and specifying the line range if necessary, though typically placing the comment right above the class keyword is sufficient for the scanner to recognize the intent until the end of the class definition.
Trade-offs and Best Practices
Using suppression comments is a pragmatic solution, but it comes with caveats. Primarily, this pattern indicates a deviation from standard architectural guidelines. PSR-12 recommends that each file contain only one class or interface definition. When you merge implementation and testing code, you are essentially telling future developers (and automated tools) that the separation of concerns is being relaxed for convenience or legacy reasons.
If your team relies heavily on static analysis tools beyond just PHPCS, such as PHPStan or Psalm, these tools might still flag the file structure as suspicious. While they won't necessarily error out based on the "one class per file" rule in the same way PHPCS does, they may generate warnings about testing logic mixing with production logic. This can make it harder to reason about code complexity and performance impact, as tests are often executed differently than production code.
Another pitfall is relying too heavily on suppression directives. If you find yourself needing to suppress OneClassPerFile in every test file, it might be worth considering if your project structure truly supports separating tests into their own directories or files. Many modern PHP projects use a directory named tests/ or Tests/ where each file contains only the relevant test class. This naturally satisfies PHPCS without needing any suppression comments.
Configuration Considerations
If you are managing a large codebase and want to apply this rule globally, you can adjust the ruleset in your .phpcs.xml or .phpcs.xml.dist file. You could add a custom rule set or modify the Generic.Files.OneClassPerFile rule to have lower severity or disable it entirely for specific directories using the exclude_paths configuration option.
For example, adding an exclusion path like */tests/* to your PHPCS configuration will automatically ignore this rule for all files within that directory. This is often cleaner than scattering comments throughout your code. However, if you are working on a smaller utility script or a specific legacy module where file separation isn't feasible, the inline suppression remains the most direct and effective method.
Ultimately, the decision to suppress lies with your team's coding standards policy. If the project prioritizes quick iteration over strict structural purity, suppressing the warning is acceptable. Just remember that every suppression comment is a reminder that the ideal architectural practice wasn't followed in that specific location.
