You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
You are generating documentation pages for PHPStan error identifiers. PHPStan is a PHP static analysis tool that finds bugs in code without running it. Each error identifier (like `argument.type`, `deadCode.unreachable`, `property.notFound`) categorizes a specific type of error.
58
-
58
+
59
59
The goal is to create a markdown file for each identifier in `website/errors/` explaining what the error means, showing a code example, and offering ways to fix it.
60
-
60
+
61
61
## Step 1: Find what changed
62
-
62
+
63
63
See the checked out commit of the current repository. It should contain changes to `website/src/errorsIdentifiers.json`. See if the diff means any identifier was added or updated.
64
-
64
+
65
65
Read `website/src/errorsIdentifiers.json`. This JSON maps each identifier to its rule classes and source code locations:
66
-
66
+
67
67
```json
68
68
{
69
69
"argument.type": {
@@ -75,21 +75,21 @@ jobs:
75
75
}
76
76
}
77
77
```
78
-
78
+
79
79
Then list existing files in `website/errors/`. Each file is named `<identifier>.md`.
80
-
80
+
81
81
You will document any identifiers that do not have .md file. You will also look if any identifiers involved in the diff of the checked out commit need updating the docs.
82
-
82
+
83
83
## Step 2: Clone required repositories
84
-
84
+
85
85
Clone only the repositories referenced by the affected identifiers. Extract the branch name from the GitHub URLs (e.g., `blob/2.2.x/` → branch `2.2.x`).
For each identifier, gather the information needed to write the documentation.
105
-
105
+
106
106
### 3a. Read the rule source code
107
-
107
+
108
108
From the JSON URLs, extract the file path and line number. Read the source code around those lines to find:
109
-
109
+
110
110
1. **Error message**: Look for `RuleErrorBuilder::message('...')` — this is the exact error text PHPStan shows
111
111
2. **Trigger condition**: Read the surrounding `processNode()` method to understand what code pattern causes this error
112
112
3. **Tips**: Look for `->tip('...')` or `->addTip('...')` calls in the same builder chain — these often contain links to blog posts or documentation pages on phpstan.org
113
113
4. **Non-ignorable**: Check for `->nonIgnorable()` in the builder chain
114
-
114
+
115
115
### 3b. Understand the identifier prefix when source uses `$location->createIdentifier()`
116
-
116
+
117
117
When reading the rule source code in step 3a, check whether the linked source code line uses `$location->createIdentifier()`. If it does, the identifier prefix comes from `ClassNameUsageLocation` in phpstan-src, and the prefix indicates a specific PHP language feature — which may not be obvious from the prefix name alone.
118
-
118
+
119
119
If the source code does **not** use `$location->createIdentifier()`, the prefix is set directly by the rule and typically describes its PHP feature straightforwardly.
120
-
120
+
121
121
Consult the "Identifier prefix reference" section in `website/errors/CLAUDE.md` for the complete prefix-to-PHP-feature mapping tables.
122
-
122
+
123
123
### 3c. Find test fixtures with code examples
124
-
124
+
125
125
For a rule class like `PHPStan\Rules\Functions\CallToFunctionParametersRule`:
126
126
- Test class: `tests/PHPStan/Rules/Functions/CallToFunctionParametersRuleTest.php`
127
127
- Test data: `tests/PHPStan/Rules/Functions/data/*.php`
128
-
128
+
129
129
For extension repos (phpstan-doctrine, phpstan-symfony, etc.), the path pattern may differ — check `tests/Rules/` or `tests/` directories.
130
-
130
+
131
131
Read the test class to find which data files trigger this specific identifier. Look for the error message text in the test assertions:
Then read the corresponding data file to extract a minimal code example.
140
-
140
+
141
141
### 3d. Determine if the error is ignorable
142
-
142
+
143
143
An error identifier is **not ignorable** if:
144
144
- The source code uses `->nonIgnorable()` in the error builder chain
145
145
- The identifier starts with `phpstan.` (internal PHPStan errors)
146
146
- The identifier starts with `phpstanPlayground.` (playground-specific)
147
-
147
+
148
148
All other identifiers are ignorable.
149
-
149
+
150
150
### 3e. Check for configuration options
151
-
151
+
152
152
Some rules accept constructor parameters from PHPStan configuration. Look at the rule class constructor for injected config values. Cross-reference with `website/src/config-reference.md` to find the documented parameter name.
153
-
153
+
154
154
Examples of configurable rules:
155
155
- Rules that check strict types may be controlled by `treatPhpDocTypesAsCertain`
156
156
- Dead code rules may be controlled by `checkAlwaysTrueCheckTypeFunctionCall`
157
157
- Some rules are only active at certain PHPStan levels
158
-
158
+
159
159
## Step 4: Generate markdown files
160
-
160
+
161
161
Create `website/errors/` directory if it doesn't exist.
162
-
162
+
163
163
For each identifier, create `website/errors/<identifier>.md` following the file format, content guidelines, and tone described in `website/errors/CLAUDE.md`. Read that file before generating any markdown.
164
164
165
165
Each file's frontmatter MUST include a `shortDescription` field — one sentence (ending with a period) describing when the error is reported, from a user's perspective. For example: `"Accessing a private property from outside the declaring class."` or `"Loose comparison using == will always evaluate to true."`. This description should capture the essence of the error — what code pattern triggers it — without mentioning PHPStan internals.
@@ -170,13 +170,13 @@ jobs:
170
170
171
171
1. /tmp/commit-message.txt - A concise commit message (first line: short summary under 72 chars, then a blank line, then a few bullet points describing key changes). Example:
172
172
Update error docs - added new `new.trait` identifier
173
-
173
+
174
174
More detailed description of the commit
175
175
2. /tmp/pr-description.md - A pull request description in this format:
176
176
What was the work involved in updating the docs.
177
177
178
178
These files are critical - they will be used for the commit message and PR description.
0 commit comments