yCodeTech PHPCS Standard

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

Requirements

• php >= 7.2
• squizlabs/php_codesniffer 3.13+ || 4.x

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 (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.

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.