CLAUDE.md

1# PHPStan Error Identifier Documentation
2 
3This directory contains markdown documentation files for PHPStan error identifiers. Each file explains what a specific error means, shows a triggering code example, and offers ways to fix it.
4 
5## How these files are generated
6 
7Files are generated by a GitHub Actions workflow (`.github/workflows/generate-error-docs.md`) that uses Claude to:
8 
91. Read `website/src/errorsIdentifiers.json` which maps each identifier to its rule classes and source code locations
102. Pick undocumented identifiers (ones without a corresponding `.md` file here)
113. Clone referenced PHPStan repositories (`phpstan-src`, `phpstan-strict-rules`, `phpstan-doctrine`, etc.)
124. Research each identifier by reading rule source code and test fixtures
135. Generate a markdown file for each identifier
14 
15## File format
16 
17Each file follows this exact structure:
18 
19```markdown
20---
21title: "<identifier>"
22shortDescription: "One sentence describing when this error is reported."
23ignorable: true
24---
25 
26## Code example
27 
28` ``php
29<?php declare(strict_types = 1);
30
31// Minimal PHP code that triggers this error
32` ``
33 
34## Why is it reported?
35 
36Explanation from PHP language perspective.
37 
38## How to fix it
39 
40Ways to fix the error.
41```
42 
43### Frontmatter
44 
45- `title`: The error identifier (e.g., `"property.notFound"`)
46- `shortDescription`: One sentence (ending with a period) describing when the error is reported. Written from a user's perspective — what code pattern causes PHPStan to report this error. Examples: `"Accessing a private property from outside the declaring class."`, `"Loose comparison using == will always evaluate to true."`, `"Pure function uses print, which produces output as a side effect."`
47- `ignorable`: `true` for most identifiers. Set to `false` for identifiers that use `->nonIgnorable()` in the rule builder chain, or that start with `phpstan.` or `phpstanPlayground.`
48 
49### Code example
50 
51- Must be valid PHP that triggers the identifier
52- Starts with `<?php declare(strict_types = 1);`
53- Uses `php` language tag
54- Keep it minimal — remove unrelated classes, simplify names
55- Prefer real code from test fixtures when possible
56 
57### "Why is it reported?" section
58 
59- Explain PHP language semantics, not PHPStan internals
60- PHPStan points to code that causes crashes, doesn't execute at all, or doesn't do what the developer probably intended
61- Be concise and technically precise
62- List multiple reasons if applicable
63- If the rule's `->tip()` links to a blog post on phpstan.org, mention it: `Learn more: [Blog post title](/blog/post-slug)`
64 
65### "How to fix it" section
66 
67- Offer multiple ways to fix when applicable
68- Use `diff-php` syntax for code changes
69- Prefer fixes in this order:
70  1. Fix the actual bug
71  2. Narrow the type using native PHP type declarations
72  3. Narrow the type using PHPDoc types (`@param`, `@return`, `@var` on properties)
73  4. Use [type narrowing](/writing-php-code/narrowing-types) in the function body
74  5. Configure PHPStan if the rule is configurable
75- When the error involves a PHP language feature only available in newer PHP versions, mention the PHPDoc-based alternative that works on older versions too. For example: native return type `never` (PHP 8.1+) can be replaced with `@return never`, native union types (PHP 8.0+) can be expressed as PHPDoc union types, native intersection types (PHP 8.1+) can be expressed as PHPDoc intersection types, standalone types like `true`/`false`/`null` (PHP 8.2+) can be written in PHPDoc. Link to [PHPDoc Basics](/writing-php-code/phpdocs-basics) and [PHPDoc Types](/writing-php-code/phpdoc-types) where relevant.
76- Every time a configuration parameter is mentioned, link it to the correct documentation page. Consult `website/src/config-reference.md` to find the right anchor — parameters that have their own `###` heading (like `phpVersion`) link to `/config-reference#phpversion`. Parameters that only appear as "Related config keys" link to the user guide page referenced there (e.g., `reportUnmatchedIgnoredErrors` links to `/user-guide/ignoring-errors#reporting-unused-ignores`, `scanFiles` links to `/user-guide/discovering-symbols#third-party-code-outside-of-composer-dependencies`).
77- Show code fixes. Use `diff-php` syntax when showing changes:
78 
79```markdown
80```diff-php
81- $value = $this->getValue();
82+ $value = (string) $this->getValue();
83```
84```
85 
86### Do NOT
87 
88- Suggest using `assert()` for type narrowing
89- Suggest throwing an exception to narrow types
90- Suggest using inline `@var` PHPDoc tag
91- Suggest ignoring the error (the detail page already covers that)
92- Use emojis or first person
93 
94## Identifier prefix reference
95 
96Some prefixes are non-obvious because they come from `ClassNameUsageLocation`:
97 
98| Prefix | PHP Feature |
99|--------|-------------|
100| `assert` | `@phpstan-assert` PHPDoc tag (NOT `assert()` function) |
101| `attribute` | PHP 8.0+ attributes `#[AttributeName]` |
102| `catch` | `catch (ExceptionClass $e)` blocks |
103| `classConstant` | `ClassName::CONSTANT` access |
104| `instanceof` | `$x instanceof ClassName` expressions |
105| `methodTag` | `@method` PHPDoc tag |
106| `mixin` | `@mixin` PHPDoc tag |
107| `new` | `new ClassName()` instantiation |
108| `parameter` | Native type declaration on function/method parameter |
109| `property` | Native type declaration on class property (e.g., `private Foo $bar`) |
110| `propertyTag` | `@property` PHPDoc tag |
111| `requireExtends` | `@phpstan-require-extends` PHPDoc tag |
112| `requireImplements` | `@phpstan-require-implements` PHPDoc tag |
113| `return` | Native return type declaration |
114| `sealed` | `@phpstan-sealed` PHPDoc tag |
115| `selfOut` | `@phpstan-self-out` PHPDoc tag |
116| `staticMethod` | `ClassName::method()` static method calls |
117| `staticProperty` | `ClassName::$property` static property access |
118| `traitUse` | `use TraitName` in a class body |
119| `typeAlias` | PHPStan type alias references |
120| `varTag` | `@var` PHPDoc tag |
121 
122### Prefixes with special identifier format
123 
124| Prefix pattern | PHP Feature |
125|----------------|-------------|
126| `class.extends*` | `class Foo extends ParentClass` |
127| `class.implements*` | `class Foo implements Interface` |
128| `enum.implements*` | `enum Foo implements Interface` |
129| `interface.extends*` | `interface Foo extends OtherInterface` |
130| `generics.*Bound` | `@template T of BoundClass` bound constraint |
131| `generics.*Default` | `@template T = DefaultClass` default value |
132 
133## Tone and style
134 
135- Concise, technically precise, no filler words
136- Match existing phpstan.org documentation style
137- Direct and practical
138- For extension-specific identifiers (phpstan-doctrine, phpstan-symfony, etc.), mention which extension package provides the rule
139 
140## Example
141 
142For `website/errors/deadCode.unreachable.md`:
143 
144```markdown
145---
146title: "deadCode.unreachable"
147shortDescription: "Code after a return, throw, or other terminating statement can never be executed."
148ignorable: true
149---
150
151## Code example
152
153` ``php
154<?php declare(strict_types = 1);
155 
156function doFoo(): int
157{
158	return 1;
159	echo 'unreachable';
160}
161` ``
162
163## Why is it reported?
164
165The statement after `return` can never be executed. The `return` statement unconditionally transfers control out of the function, making any code following it in the same block dead code. This usually indicates a logic error or leftover code from refactoring.
166
167## How to fix it
168
169Remove the unreachable code:
170
171` ``diff-php
172 function doFoo(): int
173 {
174 	return 1;
175-	echo 'unreachable';
176 }
177` ``
178
179If the code should execute, restructure the logic so it runs before the return:
180
181` ``diff-php
182 function doFoo(): int
183 {
184+	echo 'this should run';
185 	return 1;
186-	echo 'unreachable';
187 }
188` ``
189```
190