Skip to content

yCodeTech/phpcs-standard

Repository files navigation

yCodeTech PHPCS Standard

Latest Stable Version Minimum PHP Version PHPCS Version Unit Tests

A custom PHP_CodeSniffer standard that enforces opinionated type and docblock rules with auto-fixing capabilities.

Requirements

  • php >= 7.2

Installation

# Per project: $ composer require ycodetech/phpcs-standard # Globally $ composer global require ycodetech/phpcs-standard

Sniffs

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. ✔️

Violation Codes:

yCodeTech.Commenting.DocblockFormat.TagSpacing

yCodeTech.Commenting.DocblockFormat.ReturnSpacing

Examples:

✔️ 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.

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. ✔️
Generator functions must have a @return tag. ✔️
  • Fixes with an iterable return type.

Violation Codes:

yCodeTech.Commenting.FunctionComment.MissingReturn

yCodeTech.Commenting.FunctionComment.VoidReturnTagFound

Examples:

✔️ 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.

Violation Codes:

yCodeTech.Types.DisallowTypeLongNames.DocblockType

yCodeTech.Types.DisallowTypeLongNames.TypeDeclaration

yCodeTech.Types.DisallowTypeLongNames.TypeCast

Examples:

✔️ 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;

Testing

To test the standard against the provided comprehensive test file, please see the specific instructions.

Unit Tests

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.