A custom PHP_CodeSniffer standard that enforces opinionated type and docblock rules with auto-fixing capabilities.
- php >= 7.2
- squizlabs/php_codesniffer 3.13+ || 4.x
# Per project:
$ composer require ycodetech/phpcs-standard
# Globally
$ composer global require ycodetech/phpcs-standard
yCodeTech.Commenting.DocblockFormat
Enforces 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
*/ |
yCodeTech.Commenting.FunctionComment
Functions that return a value must have a @return docblock tag (nested anonymous function and closure returns will be ignored).
| Rules | Fixable? | Notes |
|---|
| Functions with non-void return types (string, bool, etc.) must have a @return tag.
|
✔️ |
-
Fixes with a mixed return type.
-
Magic methods (e.g. __construct, __get, etc.) are exempt.
|
| Functions with void return types must NOT have @return tags, except generator functions.
|
✔️ |
- Most magic methods are exempt, except for those that return void:
__construct,
__destruct,
__clone,
__set,
__unset,
__wakeup, and
__unserialize.
|
| Generator functions must have a @return tag.
|
✔️ |
- Fixes with an iterable return type.
|
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";
} |
yCodeTech.Types.DisallowTypeLongNames
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 |
-
Docblocks and type declarations include union and nullable types.
-
Docblock types can also include generic types.
-
Types will only be fixed in these regular docblocks tags:
@param, @return, @var, @property, @method.
Also any other tags that contain the regular tags; example:
@property-read, @phpstan-param, @psalm-return.
-
Any types in docblock descriptions will not get fixed.
|
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; |
yCodeTech.Types.DisallowVoidType
Explicit void return type declarations are disallowed on functions, methods, and closures. The absence of a return type already implies void.
| Rules | Fixable? |
|---|
| Explicit : void return type declarations must be removed. |
✔️ |
yCodeTech.Types.DisallowVoidType.Found
| ✔️ Valid: No return type (implicitly void) |
❌ Invalid: Explicit void return type |
function doSomething()
{
echo "Hello";
} |
function doSomething(): void
{
echo "Hello";
} |
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 test
Each test file contains deliberate violations that should be detected by the corresponding sniff.