From 9e07e5ac60e1c87e2de12a915b184a61ba26310a Mon Sep 17 00:00:00 2001 From: mscherer Date: Tue, 12 May 2026 02:34:06 +0200 Subject: [PATCH 1/2] Document DocBlockTagOrder configuration Add a docs/README.md section covering the three public properties of PhpCollective.Commenting.DocBlockTagOrder: order (function/method docblocks), classOrder (class/interface/trait docblocks), and innerOrder (within-bucket ordering with prefix patterns). These were only discoverable by reading the sniff source. Includes both common innerOrder recipes (CRUD method ordering plus alphabetized property lists), notes the asymmetric handling of the leading at-sign on tag names between order/classOrder and innerOrder keys, and explains the InnerOrderInvalid error code as a scoping lever for keeping inner ordering on tables/views/controllers while skipping entity docblocks where DB-schema order is meaningful. --- docs/README.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/docs/README.md b/docs/README.md index f22ed51..974590e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -98,6 +98,65 @@ To enable checking for (and auto-fixing) invalid `: void` return types on these ``` +## Customize DocBlock tag ordering +`PhpCollective.Commenting.DocBlockTagOrder` enforces a consistent tag order in docblocks for functions, methods, classes, interfaces, and traits. Three properties can be overridden via XML. + +### Function/method docblock order +Default: `deprecated`, `see`, `param`, `throws`, `return`. Tags not in the list keep their relative position above the listed ones. The leading `@` on tag names is optional and gets normalized. +```xml + + + + + +``` + +### Class/interface/trait docblock order +Default: `template`, `extends`, `implements`, `property`, `property-read`, `property-write`, `method`, `mixin`. Independent of `order` so function and class docblocks can be tuned separately. +```xml + + + + + +``` + +### Inner (within-bucket) ordering +Optional. When configured, orders tags *within* a bucket. Only applies to class/interface/trait docblocks - per-method `@param` / `@return` tags are positional and have no within-bucket subject. + +Each entry's value is a comma-separated list of prefix patterns. A trailing `*` matches any suffix; a bare pattern matches only the exact subject. Tags matching no pattern float to the bottom of their bucket. Within each score class (matched-by-same-pattern, or all-unmatched), tags are sorted alphabetically by extracted subject. + +An empty value means "alphabetize the whole bucket" - the typical recipe for `@property` association lists generated by IDE helpers. + +Example covering both recipes (CRUD method order plus alphabetized property lists): +```xml + + + + + + + + + + +``` + +Note: `innerOrder` keys are matched literally - the leading `@` is required, unlike for `order` / `classOrder`. + +#### Scoping innerOrder out of entity docblocks +On CakePHP-style entities the property docblocks list columns in DB schema order (id first, logical fields together, timestamps last). That order is meaningful and stays in sync with `cakephp-ide-helper` regeneration. Alphabetizing breaks column groupings (`lat` / `lng` / `location`, `beginning` / `end`, `lft` / `rght`) and creates churn against the IDE helper. + +Inner-order violations are emitted under a separate `InnerOrderInvalid` error code so they can be suppressed independently from the bucket-level `OrderInvalid`: +```xml + + */src/Model/Entity/* + +``` + +Tables, views, and controllers still receive inner ordering in the same project. + ## Excluding test related comparison files If you want to exclude certain generated (e.g. PHP) files, make sure those are in a `test_files` subfolder to be auto-skipped. You can otherwise always create a custom and rather unique folder name and manually exclude it in your PHPCS settings. From 4a8fd08e32c769122aabcd982f8ffc148ac4c1a8 Mon Sep 17 00:00:00 2001 From: Mark Scherer Date: Tue, 12 May 2026 10:32:39 +0200 Subject: [PATCH 2/2] Update README.md --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 974590e..1611052 100644 --- a/docs/README.md +++ b/docs/README.md @@ -134,7 +134,7 @@ Example covering both recipes (CRUD method order plus alphabetized property list + value="newEmptyEntity,newEntity,newEntities,get,find*,findOrCreate,patchEntity,patchEntities,save,saveOrFail,saveMany*,delete,deleteOrFail,deleteMany*"/>