A custom PHP_CodeSniffer standard that enforces opinionated type and docblock rules with auto-fixing capabilities.
php >= 7.2
# Per project: $ composer require ycodetech/phpcs-standard # Globally $ composer global require ycodetech/phpcs-standardEnforces proper spacing and formatting in docblocks.
| Rules | Fixable? |
|---|---|
All docblock tags must have exactly 1 space between each element. | ✔️ |
The type and variable in any tag must be separated by a space. | ✔️ |
@return tags must be preceded by exactly 1 empty line. | ✔️ |
yCodeTech.Commenting.DocblockFormat.TagSpacing
yCodeTech.Commenting.DocblockFormat.ReturnSpacing
| ✔️ Valid: Exactly 1 space between tag elements | ❌ Invalid: Multiple spaces between tag elements |
|---|---|
/** * @param string $name The name parameter * @throws Exception If something goes wrong * @see SomeClass For more information * @var string * @copyright Copyright (c) year, Name */ | /** * @param string $name The name parameter * @throws Exception If something goes wrong * @see SomeClass For more information * @var string * @copyright Copyright (c) year, Name */ |
| ✔️ Valid: Exactly 1 space between type and variable | ❌ Invalid: 0 spaces between type and variable |
|---|---|
/** * @param string $name The name parameter */ | /** * @param string$name The name parameter */ |
| ✔️ Valid: Exactly 1 empty line before @return tag | ❌ Invalid: 0 empty lines before @return tag |
|---|---|
/** * @param string $name The name parameter * * @return string */ | /** * @param string $name The name parameter * @return string */ |
| ✔️ Valid: Exactly 1 empty line before @return tag | ❌ Invalid: Multiple empty lines before @return tag |
|---|---|
/** * @param string $name The name parameter * * @return string */ | /** * @param string $name The name parameter * * * * @return string */ |
Functions that return a value must have a @return docblock tag.
| Rules | Fixable? | Notes |
|---|---|---|
Functions with non-void return types (string, bool, etc.) must have a @return tag. | ✔️ |
|
Functions with void return types must NOT have @return tags, except generator functions. | ✔️ | |
Generator functions must have a @return tag. | ✔️ |
|
yCodeTech.Commenting.FunctionComment.MissingReturn
yCodeTech.Commenting.FunctionComment.VoidReturnTagFound
| ✔️ Valid: @return tag for non-void function | ❌ Invalid: Missing @return tag for non-void function |
|---|---|
/** * Get formatted string. * * @param string $input The input string * * @return string */ public function formatString(string $input): string { } | /** * Get formatted string. * * @param string $input The input string */ public function formatString(string $input): string { } |
| ✔️ Valid: No @return for void function | ❌ Invalid: @return tag on void function |
|---|---|
/** * Process data without returning anything. * * @param array $data The data to process */ public function processData(array $data): void { } | /** * Process data without returning anything. * * @param array $data The data to process * * @return void */ public function processData(array $data): void { } |
| ✔️ Valid: @return tag for generator function | ❌ Invalid: Missing @return tag for generator function |
|---|---|
/** * Get formatted string. * * @param string $input The input string * * @return iterable */ public function formatString(string $input) { yield "Hello $input"; } | /** * Get formatted string. * * @param string $input The input string */ public function formatString(string $input) { yield "Hello $input"; } |
Long type names are disallowed. Short names must be used in docblocks, type declarations, and type casting.
| Rules | Fixable? |
|---|---|
Use bool instead of boolean. | ✔️ |
Use int instead of integer. | ✔️ |
| Notes |
|
yCodeTech.Types.DisallowTypeLongNames.DocblockType
yCodeTech.Types.DisallowTypeLongNames.TypeDeclaration
yCodeTech.Types.DisallowTypeLongNames.TypeCast
| ✔️ Valid: Short name docblock types | ❌ Invalid: Long name docblock types |
|---|---|
/** * @param bool $isValid * @psalm-param bool $isValid * * @return int */ | /** * @param boolean $isValid * @psalm-param boolean $isValid * * @return integer */ |
| ✔️ Valid: Short name docblock generic types | ❌ Invalid: Long name docblock generic types |
|---|---|
/** * @param Collection<int> $numbers * @param Map<string, bool> $settings * @param array<string, int> $counts * @param array<bool, int> $counts */ | /** * @param Collection<integer> $numbers * @param Map<string, boolean> $settings * @param array<string, integer> $counts * @param array<boolean, integer> $counts */ |
| ✔️ Valid: Short name class property type declarations | ❌ Invalid: Long name class property type declarations |
|---|---|
private bool $isActive; protected int $userCount; | private boolean $isActive; protected integer $userCount; |
| ✔️ Valid: Short name function/method/closure types | ❌ Invalid: Long name function/method/closure types |
|---|---|
function foo(bool $flag): int { $callback = function(bool $isValid): int { }; } | function foo(boolean $flag): integer { $callback = function(boolean $isValid): integer { }; } |
| ✔️ Valid: Short name nullable and union types | ❌ Invalid: Long name nullable and union types |
|---|---|
function foo(?bool $flag, bool|string $var): ?int { } | function foo(?boolean $flag, boolean|string $var): ?integer { } |
| ✔️ Valid: Short name type casting | ❌ Invalid: Long name type casting |
|---|---|
$foo = (bool) $isValid; $bar = (int) $count; | $foo = (boolean) $isValid; $bar = (integer) $count; |
To test the standard against the provided comprehensive test file, please see the specific instructions.
Run the comprehensive test suite:
# Test all sniff unit tests $ composer testEach test file contains deliberate violations that should be detected by the corresponding sniff.