Let's Build a Tiny PHPStan

Ondřej Mirtes who builds PHPStan made English slides for me!
https://github.com/asumikam/ministan/issues/1

Special Thanks tadsan!!!!
https://phpc.social/@zonuexe/117374503287394028
https://github.com/phpstan/phpstan/issues/15355

1. Let's Build a Tiny PHPStan asumikam
2. PHPStan
3. Find Bugs Without Writing Tests • A static analysis tool for PHP that finds potential bugs without running your code • Uses type declarations to catch errors early: undefined variables and methods, type mismatches, and more • Choose how strict to be with levels 0–10
5. You can write “custom rules” too • Besides the rules PHPStan ships with, you can create your own rules to enforce • Great for enforcing the rules of your domain
6. For example, “Ban var_dump” Let's write it as a custom rule
8. The rule applies when a function call shows up in the code
9. If the function name is var_dump ⇒ report an error
10. With just this,*1 it actually applies the rule for you *1 In practice you also tweak phpstan.neon a little, but that's a minor detail
11. Amazing!!
12. But how!?
13. If you don't get it, just read it
14. Files ~2,000 Lines ~200,000 * excl. blank lines
15. That's huuuge!
16. • At first, I didn't even know where to start reading • Instead of understanding the details (micro) first, grasp the big picture (macro), then read the real thing • Build something “less than PHPStan” as a roadmap for reading the real thing
17. While respecting the real flow, “Build It Small”
18. Goal of This Talk Through my “Build It Small” version, people who don't know PHPStan's internals get a rough picture of how it works inside!
19. Asumi (@asumikam) 🍊 • Linkage, Inc. • PHPer • Agile / Scrum • Organizer of PHP Conference Odawara
20. Today's Menu 1 Build It Small 2 Compare with PHPStan
21. #1 Build It Small
22. #1 Build It Small 1. Look at the “Build It Small” implementation 2. Write some real rules
23. #1 Build It Small 1. Look at the “Build It Small” implementation 2. Write some real rules
24. #1 Build It Small How do we usually read through code?
25. #1 Build It Small
26. #1 Build It Small Is there a User class?
27. #1 Build It Small The User class exists
28. #1 Build It Small $user is a User
29. #1 Build It Small Is there a rename method? Does it take exactly one argument?
30. #1 Build It Small The rename method exists One argument — correct
31. #1 Build It Small Is there a remove method?
32. #1 Build It Small The remove method doesn't exist!
33. #1 Build It Small What I do in my head Know What to Check Does that method exist? Read the Structure Variable assignments, method calls Read Through Top to bottom, tracking each variable Apply the Checks Report When a method is called, check it “That class doesn't have that method!”
34. #1 Build It Small What I do in my head Know What to Check Read the Structure Read Through Apply the Checks Report With these five as the backbone, let's “Build It Small”: a tiny PHPStan
35. #1 Build It Small How small are we going? PHPStan ministan Files ~2,000 8 Lines (excl. blank lines, etc.) ~200,000 220 ministan still has a fair amount of code, so in this talk I'll explain it so you can get a rough feel for it
36. #1 Build It Small https://github.com/asumikam/ministan
37. #1 Build It Small $ php bin/ministan AnalyzeTarget.php
38. #1 Build It Small The file to analyze $ php bin/ministan AnalyzeTarget.php
39. #1 Build It Small Let's take a look at ministan $ php bin/ministan AnalyzeTarget.php
41. Read the Structure Know What to Check Apply the Checks Read Through Report
42. Read the Structure Know What to Check Apply the Checks Read Through Report
43. #1 Build It Small Building “Read the Structure” • Source code is just a sequence of characters • Humans just skim back and forth, and it works • For a machine to read it, you need fixed rules • Break the code into “meaningful chunks”
44. #1 Build It Small AST (Abstract Syntax Tree) • Abstract Syntax Tree • Split code into “meaningful chunks” = “nodes”, arranged as a tree • Nodes come in kinds (assignment, method call, variable…) • Things irrelevant to meaning, like “;” and whitespace, are thrown away • PHPStan builds the AST with php-parser (nikic/php-parser)
45. #1 Build It Small
46. #1 Build It Small
47. #1 Build It Small All of these are nodes Stmt_Expression Expr_Variable Expr_New Name Expr_MethodCall Identifier Arg Scalar_String
48. #1 Build It Small • Starts with an array of Stmt • Line 1 0: Stmt_Expression • Line 2 1: Stmt_Expression • Walking the AST parent → child = reading code line by line, top to bottom, outside in
49. #1 Build It Small • Nodes contain more nodes (nesting) • Node • Array of nodes • Plain value
50. $ast holds the file to analyze, converted into an AST
51. Know What to Check
52. #1 Build It Small Building “Know What to Check” • Implement rules like the one we saw in the intro • List the rules you want to enable in an array • Pass $ast in the constructor so a rule can look up definitions (functions, classes) • What a concrete Rule looks like comes later
53. Apply the Checks
54. #1 Build It Small Building “Apply the Checks” • Take one node and check it with the rules matching its kind • Receive the rules to use through the constructor • It runs once per node, so instead of printing errors right away, collect them and “Report” them all at the end • It actually runs during “Read Through”
55. #1 Build It Small
56. #1 Build It Small The rules to apply come in as constructor args
57. #1 Build It Small The argument is expected to be the node to check
58. #1 Build It Small Loop over the rules to apply
59. #1 Build It Small If a rule's node type matches the kind of node passed in
60. #1 Build It Small Check with the rule (if it fails, a message comes back)
61. #1 Build It Small If anything comes back, it's an error, so stash it in $errors
62. #1 Build It Small Collect errors while “applying the rules”
63. #1 Build It Small We'll use this later
64. Read Through
65. #1 Build It Small Building “Read Through” • Walk the AST from parent to child, top to bottom • The same motion as the “read line by line” we humans did • Every time we reach a node, call “Apply the Checks”
66. #1 Build It Small
67. #1 Build It Small
68. #1 Build It Small At first, the whole file's AST ($ast) is passed in $nodeCallback is the one we built in “Apply the Checks”
69. #1 Build It Small Loop over $nodes and pass each one to processNode
70. #1 Build It Small
71. #1 Build It Small Apply the Checks!!
72. #1 Build It Small Nodes are nested, so walk the child nodes recursively
73. #1 Build It Small
75. Report
76. $nodeCallback has the errors, so we ask it
77. I totally get it
78. Let's write some real rules
79. #1 Build It Small 1. Look at the “Build It Small” implementation 2. Write some real rules
80. #1 Build It Small “Does the function / method exist?” — let's implement it as a rule
81. #1 Build It Small “Does the function / method exist?” myfunc('xxx') Function call Class::method() Static method call on a class $this->method() Call via $this inside a class $some->method() Method call via a variable
82. #1 Build It Small “Does the function / method exist?” myfunc('xxx') Function call Class::method() Static method call on a class $this->method() Call via $this inside a class $some->method() Method call via a variable
83. #1 Build It Small I want an error when the function doesn't exist // <- HERE!!
84. #1 Build It Small Let's write the rule
85. #1 Build It Small
86. #1 Build It Small When the node is a function call
87. #1 Build It Small Apply the rule
88. #1 Build It Small Get the function name of the node being checked
89. #1 Build It Small Pull every function definition out of the whole code ($ast)
90. #1 Build It Small Look for a matching function If it exists, OK
91. #1 Build It Small If it doesn't exist, return an error message
92. #1 Build It Small Corresponding PHPStan rule: CallToNonExistentFunctionRule (level 0+)
93. #1 Build It Small “Does the function / method exist?” myfunc('xxx') Function call Class::method() Static method call on a class $this->method() Call via $this inside a class $some->method() Method call via a variable
94. #1 Build It Small I want an error when the static method doesn't exist // <- HERE!!
95. #1 Build It Small Let's write the rule
96. #1 Build It Small
97. #1 Build It Small When the node is a static call
98. #1 Build It Small
99. #1 Build It Small Get the class name & method name of the node being checked
100. #1 Build It Small Get all the classes in the whole code → loop over them
101. #1 Build It Small If it's not the matching class, continue
102. #1 Build It Small If the class being checked exists and has that method, OK
103. #1 Build It Small If it doesn't exist, return an error message
104. #1 Build It Small Corresponding PHPStan rule: CallStaticMethodsRule (level 0+)
105. #1 Build It Small “Does the function / method exist?” myfunc('xxx') Function call Class::method() Static method call on a class $this->method() Call via $this inside a class $some->method() Method call via a variable
106. #1 Build It Small I want an error when the method doesn't exist on $this // <- HERE!!
107. #1 Build It Small The mechanism needs an update • The AST only has the name “this” — the class name isn't written anywhere • What the pseudo-variable $this holds depends on the context • We need someone in charge of remembering what $this held
108. #1 Build It Small Let's picture “remembering what it held”
109. #1 Build It Small Reading through the AST is basically reading from top to bottom
110. #1 Build It Small Just remember it when we enter a class definition (node) “this” is “User” 🧠
111. #1 Build It Small When we reach the code further down, just use the value we remembered “this” is “User” 🧠
112. #1 Build It Small This role is called Scope
113. #1 Build It Small A Scope that remembers the class + the code that uses it
114. #1 Build It Small Implementing Scope
115. #1 Build It Small
116. #1 Build It Small Remember it when entering a class
117. #1 Build It Small So it can answer when asked
118. #1 Build It Small It gets used during “Read Through”
119. #1 Build It Small
120. #1 Build It Small Pass $scope around as an argument
121. #1 Build It Small Pass $scope around as an argument So “Apply the Checks” can use it too
122. #1 Build It Small On entering a class definition, run enterClass
123. #1 Build It Small All set!
124. #1 Build It Small Let's write the rule
125. #1 Build It Small While walking the AST, once we enter a class, the value is stored in Scope “this” is “User” 🧠
126. #1 Build It Small
127. #1 Build It Small When a method call node comes in
128. #1 Build It Small
129. #1 Build It Small Scope's turn
130. #1 Build It Small $node->var is an Expr_Variable named this ⇒ we can look up User
131. #1 Build It Small The rest is the same as before: check whether it matches
132. #1 Build It Small Corresponding PHPStan rule: CallMethodsRule (level 0+)
133. #1 Build It Small “Does the function / method exist?” myfunc('xxx') Function call Class::method() Static method call on a class $this->method() Call via $this inside a class $some->method() Method call via a variable
134. #1 Build It Small I want an error when $user doesn't have the method // <- HERE!!
135. #1 Build It Small The mechanism needs an update Scope only remembered things when entering a class definition • • Just do the same thing on assignment
136. #1 Build It Small A Scope that remembers variables + the code that uses it
137. #1 Build It Small
138. #1 Build It Small Remember it, just like we did for classes
139. #1 Build It Small Exactly the same mechanism as getting the “class name”
140. #1 Build It Small It gets used during “Read Through”
141. #1 Build It Small
142. #1 Build It Small Remembering variables
143. #1 Build It Small What the slides didn't fully cover • Before • The original Scope was only passed down “parent → child” • After • Return the processed Scope and hand it over to the next step • But what's learned inside a class isn't carried outside
144. #1 Build It Small Just by updating Scope, the same rule as before works
145. #1 Build It Small Corresponding PHPStan rule: CallMethodsRule (level 2+, depending on config)
146. #1 Build It Small Recap
148. The file to analyze
149. Read the Structure = parse into an AST
150. Know What to Check = implement & register rules
151. Apply the Checks = pick rules by node = collect errors
152. Read Through = walk while updating Scope
153. Report = print errors, if any
154. #1 Build It Small Recap • Built PHPStan's internals, but small (at express speed) • ~200,000 lines → 220 lines • Even shrunk down, the flow and the cast (the skeleton) stayed the same • That said, plenty of corners were cut • Use ministan as a stepping stone: “what's different in the real one?” • Even the rules you use daily show real craft and depth once you read them
155. #1 Build It Small Disclaimer • ministan is focused on “Build It Small”, so it is intentionally released incomplete • Compare it with the real PHPStan and enjoy its imperfections
156. #1 Build It Small ministan ↔ PHPStan Cheat Sheet PHPStan ministan ParserFactory Parser\ RichParser Rule-related Rules\ Rule, LazyRegistry FileAnalyserCallback Analyser\ FileAnalyserCallback NodeScopeResolver Analyser\ NodeScopeResolver Scope Analyser\ MutatingScope NodeFinder Reflection\ ReflectionProvider echo Command\ErrorFormatter\ ErrorFormatter
157. #2 Compare with PHPStan
158. #2 Compare with PHPStan Comparing with PHPStan • ministan works, but it's “less than PHPStan” • So: “How does the real one do it?” • Why use an AST? • How is it so fast? • How are custom rules wired in?
159. #2 Compare with PHPStan ① Why use an “AST”? • php-parser is used by many PHP tools, such as Rector and Psalm • ministan also uses php-parser as-is • If you only need “does the class have this method?”, couldn't PHP's built-in Reflection tell you?
160. #2 Compare with PHPStan ① Because “loading it means running it” • Reflection needs you to require (= execute) the file • If definitions and logic share a file, the logic runs before you can inspect • ministan also tried Reflection first, hit exactly this, and switched to finding definitions in the AST • The real PHPStan moved to “static reflection” (reading definitions from the AST) in 0.12.26 (BetterReflection) • See: https://phpstan.org/blog/zero-config-analysis-with-static-reflection
161. #2 Compare with PHPStan ② How is it so fast? • More code means more nodes, and more rules means even more loops. The repetition multiplies • Picture your own project… hundreds of files × hundreds of nodes × hundreds of rules • The real one also does type inference (computing Scope) for every node
162. #2 Compare with PHPStan ② The secrets of its speed • Pick out only the rules relevant to that node (and cache the result) • Split files into “jobs” of 20 and analyze them in parallel across multiple worker processes • Skip analyzing files that haven't changed (result cache) • And recently: a C++ extension (PHPStan Turbo), and using pcntl_fork() to skip worker startup
163. #2 Compare with PHPStan ③ How are custom rules wired in? • In ministan, I listed the rules by hand • Where does the real one line up the built-in rules and the custom rules you write? • And how do “levels” change which rules are enabled in the first place?
164. #2 Compare with PHPStan ③-1 Registering levels • Built-in rules declare “from which level they're enabled” with an attribute • #[RegisteredRule(level: 0)] • Pick level N, and only rules with level ≤ N get registered • src/DependencyInjection/AutowiredAttributeServicesExtension.php • Where rules with the attribute are collected, filtered by level, and registered
165. #2 Compare with PHPStan ③-2 Registering custom rules • Write a class name under rules: in phpstan.neon, and that rule gets registered • It goes into the same “rule list” as the built-in rules • So inside the real PHPStan, built-in and custom rules are treated the same way • src/DependencyInjection/RulesExtension.php • Where the classes listed under rules: are added to the rule list
166. ### Wrap-up
167. Goal of This Talk Through my “Build It Small” version, people who don't know PHPStan's internals get a rough picture of how it works inside!
168. Knowing what's inside the tools you use every day lets you do more and makes them less scary
169. Understanding makes it fun
170. Let's build our own!
171. Promo PHP Conference Odawara 2027 2027/04/10
172. Promo Individual sponsorships on sale 2026/10/13
173. Thanks! Thank you very much! Enjoy your PHP Conference Ehime!