From 31d52d6850a4a9f65912e864c20b8a0babe4b525 Mon Sep 17 00:00:00 2001 From: yCodeTech Date: Fri, 27 Mar 2026 00:36:02 +0000 Subject: [PATCH 1/6] docs(readme): add a table of contents --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index 54f2696..9133fe0 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,18 @@ A custom [PHP_CodeSniffer](https://github.com/PHPCSStandards/PHP_CodeSniffer/tree/4.x) standard that enforces opinionated type and docblock rules with auto-fixing capabilities. +## Table of Contents + +- [Requirements](#requirements) +- [Installation](#installation) +- [Sniffs](#sniffs) + - [yCodeTech.Commenting.DocblockFormat](#ycodetechcommentingdocblockformat) + - [yCodeTech.Commenting.FunctionComment](#ycodetechcommentingfunctioncomment) + - [yCodeTech.Types.DisallowTypeLongNames](#ycodetechtypesdisallowtypelongnames) + - [yCodeTech.Types.DisallowVoidType](#ycodetechtypesdisallowvoidtype) +- [Testing](#testing) + - [Unit Tests](#unit-tests) + ## Requirements - `php >= 7.2` From b46d8dc89c7fc435416c75f4e011d3e49e0fec9c Mon Sep 17 00:00:00 2001 From: yCodeTech Date: Fri, 27 Mar 2026 02:22:49 +0000 Subject: [PATCH 2/6] chore(prettier): add markdown files to Prettier overrides for formatting --- .prettierrc.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.prettierrc.json b/.prettierrc.json index 68a890a..4ba9e80 100644 --- a/.prettierrc.json +++ b/.prettierrc.json @@ -3,7 +3,7 @@ "useTabs": false, "overrides": [ { - "files": ["*.yml"], + "files": ["*.yml", "*.md"], "options": { "tabWidth": 2, "useTabs": false From 8c439cafe4a3777faa4c1e9ee29106dffb88d0e7 Mon Sep 17 00:00:00 2001 From: yCodeTech Date: Fri, 27 Mar 2026 04:46:38 +0000 Subject: [PATCH 3/6] style(readme): auto formatting to remove excess spacing --- README.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 9133fe0..9beac3a 100644 --- a/README.md +++ b/README.md @@ -21,8 +21,8 @@ A custom [PHP_CodeSniffer](https://github.com/PHPCSStandards/PHP_CodeSniffer/tre ## Requirements -- `php >= 7.2` -- `squizlabs/php_codesniffer 3.13+ || 4.x` +- `php >= 7.2` +- `squizlabs/php_codesniffer 3.13+ || 4.x` ## Installation @@ -212,9 +212,9 @@ Functions that return a value must have a `@return` docblock tag (nested anonymo ✔️ -- Fixes with a mixed return type. +- Fixes with a mixed return type. -- Magic methods (e.g. \_\_construct, \_\_get, etc.) are exempt. +- Magic methods (e.g. \_\_construct, \_\_get, etc.) are exempt. @@ -397,17 +397,17 @@ Long type names are disallowed. Short names must be used in docblocks, type decl - Docblocks and type declarations include union and nullable types. -- Docblock types can also include generic types. +- Docblock types can also include generic types. -- Types will only be fixed in these regular docblocks tags: +- Types will only be fixed in these regular docblocks tags: - `@param`, `@return`, `@var`, `@property`, `@method`. + `@param`, `@return`, `@var`, `@property`, `@method`. - Also any other tags that contain the regular tags; example: + Also any other tags that contain the regular tags; example: - `@property-read`, `@phpstan-param`, `@psalm-return`. + `@property-read`, `@phpstan-param`, `@psalm-return`. -- Any types in docblock descriptions will not get fixed. +- Any types in docblock descriptions will not get fixed. From a0d06a225ff2d310e3823db31643506dc44fd239 Mon Sep 17 00:00:00 2001 From: yCodeTech Date: Fri, 27 Mar 2026 04:51:25 +0000 Subject: [PATCH 4/6] style(readme): remove indentation in tables - Remove indentation in tables to prevent auto formatting issues where the tr's or td's will be indented exponentially. - Only add indentation in where it matters for the content to be aligned properly within the table. --- README.md | 217 ++++++++++++++++++++++++++---------------------------- 1 file changed, 106 insertions(+), 111 deletions(-) diff --git a/README.md b/README.md index 9beac3a..9de24cf 100644 --- a/README.md +++ b/README.md @@ -41,25 +41,25 @@ $ composer global require ycodetech/phpcs-standard Enforces proper spacing and formatting in docblocks. - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + +
RulesFixable?
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. - ✔️
RulesFixable?
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: @@ -72,8 +72,8 @@ Enforces proper spacing and formatting in docblocks. - - + +
✔️ Valid: Exactly 1 space between tag elements❌ Invalid: Multiple spaces between tag elements✔️ Valid: Exactly 1 space between tag elements❌ Invalid: Multiple spaces between tag elements
@@ -107,8 +107,8 @@ Enforces proper spacing and formatting in docblocks. - - + +
✔️ Valid: Exactly 1 space between type and variable❌ Invalid: 0 spaces between type and variable✔️ Valid: Exactly 1 space between type and variable❌ Invalid: 0 spaces between type and variable
@@ -134,8 +134,8 @@ Enforces proper spacing and formatting in docblocks. - - + +
✔️ Valid: Exactly 1 empty line before @return tag❌ Invalid: 0 empty lines before @return tag✔️ Valid: Exactly 1 empty line before @return tag❌ Invalid: 0 empty lines before @return tag
@@ -164,8 +164,8 @@ Enforces proper spacing and formatting in docblocks. - - + +
✔️ Valid: Exactly 1 empty line before @return tag❌ Invalid: Multiple empty lines before @return tag✔️ Valid: Exactly 1 empty line before @return tag❌ Invalid: Multiple empty lines before @return tag
@@ -200,51 +200,49 @@ Enforces proper spacing and formatting in docblocks. Functions that return a value must have a `@return` docblock tag (nested anonymous function and closure returns will be ignored). - - - - - - - - - - + + + + + - - - - - - - - - - + + + + + + + + + + + + - +
RulesFixable?Notes
Functions with non-void return types (string, bool, etc.) must have a @return tag. - ✔️ +
RulesFixable?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. - ✔️ +
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: @@ -257,8 +255,8 @@ Functions that return a value must have a `@return` docblock tag (nested anonymo - - + +
✔️ Valid: @return tag for non-void function❌ Invalid: Missing @return tag for non-void function✔️ Valid: @return tag for non-void function❌ Invalid: Missing @return tag for non-void function
@@ -296,8 +294,8 @@ public function formatString(string $input): string - - + +
✔️ Valid: No @return for void function❌ Invalid: @return tag on void function✔️ Valid: No @return for void function❌ Invalid: @return tag on void function
@@ -335,8 +333,8 @@ public function processData(array $data): void - - + +
✔️ Valid: @return tag for generator function❌ Invalid: Missing @return tag for generator function✔️ Valid: @return tag for generator function❌ Invalid: Missing @return tag for generator function
@@ -379,23 +377,23 @@ public function formatString(string $input) Long type names are disallowed. Short names must be used in docblocks, type declarations, and type casting. - - - - - - - - - - - - - - - + + + + + + + + + + + + + + - - + +
RulesFixable?
Use bool instead of boolean.✔️
Use int instead of integer.✔️
Notes - -- Docblocks and type declarations include union and nullable types. +
RulesFixable?
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. @@ -409,9 +407,8 @@ Long type names are disallowed. Short names must be used in docblocks, type decl - Any types in docblock descriptions will not get fixed. -
#### Violation Codes: @@ -426,8 +423,8 @@ Long type names are disallowed. Short names must be used in docblocks, type decl - - + +
✔️ Valid: Short name docblock types❌ Invalid: Long name docblock types✔️ Valid: Short name docblock types❌ Invalid: Long name docblock types
@@ -458,8 +455,8 @@ Long type names are disallowed. Short names must be used in docblocks, type decl
- - + +
✔️ Valid: Short name docblock generic types❌ Invalid: Long name docblock generic types✔️ Valid: Short name docblock generic types❌ Invalid: Long name docblock generic types
@@ -490,8 +487,8 @@ Long type names are disallowed. Short names must be used in docblocks, type decl
- - + +
✔️ Valid: Short name class property type declarations❌ Invalid: Long name class property type declarations✔️ Valid: Short name class property type declarations❌ Invalid: Long name class property type declarations
@@ -514,8 +511,8 @@ protected integer $userCount;
- - + +
✔️ Valid: Short name function/method/closure types❌ Invalid: Long name function/method/closure types✔️ Valid: Short name function/method/closure types❌ Invalid: Long name function/method/closure types
@@ -543,8 +540,8 @@ function foo(boolean $flag): integer { - - + +
✔️ Valid: Short name nullable and union types❌ Invalid: Long name nullable and union types✔️ Valid: Short name nullable and union types❌ Invalid: Long name nullable and union types
@@ -568,8 +565,8 @@ function foo(?boolean $flag, boolean|string $var): ?integer { - - + +
✔️ Valid: Short name type casting❌ Invalid: Long name type casting✔️ Valid: Short name type casting❌ Invalid: Long name type casting
@@ -596,14 +593,12 @@ $bar = (integer) $count; Explicit `void` return type declarations are disallowed on functions, methods, and closures. The absence of a return type already implies void. - - - - - - - - + + + + + +
RulesFixable?
Explicit : void return type declarations must be removed.✔️
RulesFixable?
Explicit : void return type declarations must be removed.✔️
#### Violation Codes: @@ -614,8 +609,8 @@ Explicit `void` return type declarations are disallowed on functions, methods, a - - + +
✔️ Valid: No return type (implicitly void)❌ Invalid: Explicit void return type✔️ Valid: No return type (implicitly void)❌ Invalid: Explicit void return type
From 59f91c27793943f3d54caad36d2f9a42d819ccdc Mon Sep 17 00:00:00 2001 From: yCodeTech Date: Fri, 27 Mar 2026 04:55:52 +0000 Subject: [PATCH 5/6] style: auto formatting to remove unnecessary whitespace --- .../Sniffs/Commenting/FunctionCommentSniff.php | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/yCodeTech/Sniffs/Commenting/FunctionCommentSniff.php b/yCodeTech/Sniffs/Commenting/FunctionCommentSniff.php index 7265240..82a7038 100644 --- a/yCodeTech/Sniffs/Commenting/FunctionCommentSniff.php +++ b/yCodeTech/Sniffs/Commenting/FunctionCommentSniff.php @@ -173,7 +173,7 @@ private function hasVoidReturn(File $phpcsFile, $stackPtr) // If so, treat them as void functions for the purpose of flagging unnecessary @return tags $scopeOpener = $tokens[$stackPtr]['scope_opener'] ?? null; $scopeCloser = $tokens[$stackPtr]['scope_closer'] ?? null; - + if ($scopeOpener === null || $scopeCloser === null) { // This is an abstract function or interface method return $this->abstractFunctionHasVoidReturnTag($phpcsFile, $stackPtr); @@ -296,7 +296,7 @@ private function shouldProcessMagicMethod($functionName) /** * Check if an abstract function has a @return void tag in its docblock. - * + * * For abstract functions, if they have @return void in their docblock, * we should treat them as void functions for flagging purposes. * @@ -322,7 +322,7 @@ private function abstractFunctionHasVoidReturnTag(File $phpcsFile, $stackPtr) $stackPtr, true ); - + if ($tokenAfterComment !== false && $tokenAfterComment !== $stackPtr) { return false; } @@ -348,7 +348,7 @@ private function abstractFunctionHasVoidReturnTag(File $phpcsFile, $stackPtr) /** * Check if this is an abstract function without explicit return type. - * + * * Abstract functions without explicit return types should not be required * to have @return tags. * @@ -364,7 +364,7 @@ private function isAbstractFunctionWithoutExplicitReturn(File $phpcsFile, $stack // Check if this is an abstract function $scopeOpener = $tokens[$stackPtr]['scope_opener'] ?? null; $scopeCloser = $tokens[$stackPtr]['scope_closer'] ?? null; - + if ($scopeOpener !== null || $scopeCloser !== null) { // This is not an abstract function (has a body) return false; @@ -383,15 +383,15 @@ private function isAbstractFunctionWithoutExplicitReturn(File $phpcsFile, $stack // Look for a colon (indicating return type) after the closing parenthesis $colonPtr = $phpcsFile->findNext(T_COLON, $closeParen + 1); - + // If no colon found, or colon is after a semicolon, then no explicit return type $semicolonPtr = $phpcsFile->findNext(T_SEMICOLON, $closeParen + 1); - + if ($colonPtr === false || ($semicolonPtr !== false && $colonPtr > $semicolonPtr)) { // No explicit return type return true; } - + return false; } From 4032d3db167e3186e9091efc72ec3a0323e749b0 Mon Sep 17 00:00:00 2001 From: yCodeTech Date: Fri, 27 Mar 2026 05:22:51 +0000 Subject: [PATCH 6/6] chore: update Copilot commit message generation instructions - Added some examples to the `chore` type in the table, like editorconfig and prettier. - Added preferred types for certain changes. - `ci` for files in the `.github/workflows` directory. - `chore` for Copilot instructions. --- .../commit-message-generation.instructions.md | 46 +++++++++++-------- 1 file changed, 28 insertions(+), 18 deletions(-) diff --git a/.github/instructions/commit-message-generation.instructions.md b/.github/instructions/commit-message-generation.instructions.md index 48aa659..8694320 100644 --- a/.github/instructions/commit-message-generation.instructions.md +++ b/.github/instructions/commit-message-generation.instructions.md @@ -54,24 +54,24 @@ chore: update project files This repository extends the standard Conventional Commits types with additional project-specific types. -| Type | When to use | -| ----------- | ----------------------------------------------------------- | -| `feat` | New feature | -| `fix` | Bug fix | -| `docs` | Documentation and docblocks only | -| `style` | Formatting/whitespace, missing semi-colons, no logic change | -| `refactor` | Code restructuring, no behaviour change | -| `perf` | Performance improvement | -| `test` | Add or update tests | -| `build` | Build system or dependency changes | -| `chore` | Maintenance, tooling, config, version bumps | -| `ci` | CI/CD pipeline | -| `revert` | Revert a previous commit | -| `remove` | Remove code or files | -| `security` | Security-related changes | -| `deprecate` | Deprecation-related changes | - -## Custom Type Examples +| Type | When to use | +| ----------- | ------------------------------------------------------------------------------------------------------------ | +| `feat` | New feature | +| `fix` | Bug fix | +| `docs` | Documentation and docblocks only, but not Copilot instructions. | +| `style` | Formatting/whitespace, missing semi-colons, no logic change | +| `refactor` | Code restructuring, no behaviour change | +| `perf` | Performance improvement | +| `test` | Add or update tests | +| `build` | Build system or dependency changes | +| `chore` | Maintenance, tooling (copilot instructions, etc.), config (e.g. editorconfig, prettier, etc.), version bumps | +| `ci` | CI/CD pipeline | +| `revert` | Revert a previous commit | +| `remove` | Remove code or files | +| `security` | Security-related changes | +| `deprecate` | Deprecation-related changes | + +## Type Examples Prefer these extended types when they describe the change more accurately than `refactor`, `fix`, or `chore`. @@ -79,12 +79,22 @@ Prefer these extended types when they describe the change more accurately than ` - Use `security` when security risk reduction is the primary intent and outcome, not for unrelated fixes. - Use `deprecate` only when introducing or documenting a deprecation path, not when fully removing the deprecated code. +Prefer these types when they describe the change more accurately than any others. + +- Use `ci` for changes related to the CI/CD pipeline in the `.github/workflows` directory, not for general build or tooling changes. +- Always use `chore` for changes to Copilot instruction files that end with `.instructions.md`, not for general documentation changes. + ``` remove(drivers): delete legacy driver compatibility shim security(nginx): harden fastcgi param handling for site isolation deprecate(config): mark `php_port` as deprecated in favour of `php81_port` + +ci: update GitHub Actions workflow to use Node 18 + +chore: update Copilot commit message generation instructions + ``` ## Breaking Changes