CLAUDE.md

1# PHPStan Blog Writing Style Guide
2 
3The PHPStan blog is written by Ondrej Mirtes, creator and maintainer of PHPStan. All articles are written in first person singular ("I"). The voice is conversational, technically authoritative, and occasionally humorous.
4 
5## Voice and Tone
6 
7- **First person**: Always "I", never "we" when referring to the author's decisions (though "we" is okay when referring to the PHPStan project or community collectively, e.g. "we improved BetterReflection").
8- **Casual but knowledgeable**: Uses contractions ("it's", "doesn't", "I'm"), informal phrasing ("gonna", "dtto"), and direct address to the reader ("you").
9- **Confident and opinionated**: Doesn't hedge or equivocate. States positions clearly. e.g. "I'd absolutely avoid inheritance", "the right solutions to both of these reasons are different, and I'm gonna tell you how and why."
10- **Enthusiastic about static analysis**: Genuine excitement about features and improvements. e.g. "I've been looking forward to implementing and releasing the ideas present in PHPStan 1.10 for a long time."
11- **Self-deprecating humor**: Occasional jokes at own expense. e.g. "I automated and scaled my favourite part of being a software developer: pointing out mistakes in other people's code", or footnotes like `[^lovemyjob]: I love my job!`
12- **Emoji usage**: Very rare and restrained. Occasional use in informal contexts.
13- **Explains the "why" before the "how"**: Motivates features by describing the problem they solve, often with real-world scenarios.
14 
15## Frontmatter
16 
17Every post has YAML frontmatter:
18 
19```yaml
20---
21title: "Title in Title Case With Quotes"
22date: YYYY-MM-DD
23tags: releases  # or: guides, other
24---
25```
26 
27Tags categorize articles:
28- `releases` - Version announcements, new feature introductions
29- `guides` - Explanations, tutorials, problem-solving articles
30- `other` - Website meta, process, non-technical
31 
32## Article Types and Their Patterns
33 
34### Release Announcements (tag: releases)
35 
36Open with context about what makes this release special. Cover headline features with their own `##` sections. Each feature section explains the motivation, shows code examples, and links to documentation or playground. Often credits contributors by name with GitHub links. End with excitement about the future and the standard sponsorship CTA.
37 
38Example opening: "PHPStan 1.0 was released a little over three years ago. I'm happy to report the project is thriving! We did about 176 new releases since then..."
39 
40### Guides and Explanations (tag: guides)
41 
42Start by framing the problem or concept. Walk through solutions or explanations methodically. Heavy use of PHP code examples. Link to relevant documentation pages. Often structured as a series of solutions or approaches.
43 
44Example opening: "This error is reported for `new static()` calls that might break once the class is extended, and the constructor is overridden with different parameters."
45 
46### "Solving PHPStan error..." Series
47 
48Title format: `Solving PHPStan error "Exact error message here"`
49 
50These follow a consistent pattern:
511. Brief explanation of what triggers the error
522. Multiple solution sections, each with its own heading
533. Code examples showing the fix (often using `diff-php` syntax)
544. Links to relevant documentation
55 
56## Structure and Formatting
57 
58### Headings
59 
60Use either `##` (H2) or dashed-underline style:
61 
62```markdown
63Section title
64------------------------
65```
66 
67Both styles are used; dashed underlines are more common in guides, `##` in release announcements.
68 
69### Code Examples
70 
71- PHP code in ` ```php ` fenced blocks
72- NEON configuration in ` ```neon ` blocks
73- Diff examples use ` ```diff-php ` with `+`/`-` prefixes
74- Bash commands in ` ```bash ` blocks
75- Comments inside code explain what PHPStan reports or what types are inferred
76- Example: `// PHPStan reports: Unsafe usage of new static()`
77- Example: `\PHPStan\dumpType($d); // MyDerivative :)`
78 
79### Footnotes
80 
81Used liberally for asides, jokes, and tangential notes:
82 
83```markdown
84Something important. [^footnote]
85 
86[^footnote]: This is a tangential aside or joke.
87```
88 
89Examples:
90- `[^lovemyjob]: I love my job!`
91- `[^parcel]: It might as well mean "I can't configure Webpack and I'm not ashamed!"`
92- `[^telemetry]: This is just from my personal experience and anecdotal evidence - PHPStan doesn't perform any telemetry on user's code.`
93 
94### Links
95 
96- Cross-references to other blog posts: `[Learn more](/blog/article-slug)`
97- Links to documentation: `[configuration](/config-reference)`
98- Playground examples: `[playground example](/r/uuid-here)` or `[Link to this example on the playground](/r/uuid-here)`
99- GitHub releases: `[PHPStan 1.9.0](https://github.com/phpstan/phpstan/releases/tag/1.9.0)`
100- Credit contributors with GitHub profile links
101 
102### Embedded Tweets
103 
104Used as social proof, community reactions, or to reference prior statements. Full HTML `<blockquote class="twitter-tweet">` embeds with the Twitter widgets script.
105 
106### Markdown Abbreviations
107 
108Occasionally used for technical acronyms:
109 
110```markdown
111*[AST]: Abstract Syntax Tree
112*[OOP]: Object-Oriented Programming
113*[TLC]: Tender Loving Care
114```
115 
116### Bullet Points
117 
118Used extensively, especially for listing features, solutions, or examples. Concise, often one line each.
119 
120### Error Messages
121 
122PHPStan error messages are quoted with `>` blockquotes or inline backticks:
123 
124```markdown
125> Access to an undefined property Foo::$x.
126```
127 
128or
129 
130```markdown
131PHPStan reports "string|null is not subtype of native type string"
132```
133 
134### Images
135 
136Occasionally used for screenshots or diagrams. Format:
137 
138```markdown
139![alt text](/images/filename.png)
140```
141 
142Or with additional HTML/CSS classes for styled presentation.
143 
144### Mermaid Diagrams
145 
146Used sparingly for flowcharts:
147 
148```markdown
149{% mermaid %}
150flowchart LR;
151Node1== label ==>Node2
152{% endmermaid %}
153```
154 
155## Standard Closing
156 
157Almost every article ends with a horizontal rule and a sponsorship CTA. The exact wording has evolved over time:
158 
159Early articles:
160```markdown
161Do you like PHPStan and use it every day? [**Consider supporting further development of PHPStan on GitHub Sponsors**](https://github.com/sponsors/ondrejmirtes/). I'd really appreciate it!
162```
163 
164Recent articles:
165```markdown
166Do you like PHPStan and use it every day? [**Consider sponsoring** further development of PHPStan on GitHub Sponsors and also **subscribe to PHPStan Pro**](/sponsor)! I'd really appreciate it!
167```
168 
169Most recent:
170```markdown
171Do you like PHPStan and use it every day? [**Consider supporting further development of PHPStan**](/sponsor). I'd really appreciate it!
172```
173 
174## Content Principles
175 
1761. **Practical over theoretical**: Always show real code examples. Don't just describe - demonstrate.
1772. **Acknowledge tradeoffs**: When explaining design decisions, mention what was considered and why certain approaches were chosen.
1783. **Credit contributors**: Name individuals who contributed features, with links to their GitHub profiles.
1794. **Build on existing content**: Reference and link to previous blog posts and documentation. The blog forms an interconnected knowledge base.
1805. **Progressive disclosure**: Start with the simplest explanation or solution, then build to more complex ones.
1816. **Real-world context**: Use examples from actual frameworks (Doctrine, PHPUnit, Laravel) and real codebases (Adminer, PrestaShop) to ground explanations.
1827. **Don't talk down**: Assume the reader is a competent PHP developer who may not be familiar with type theory or static analysis concepts.
183