298
stars
24
forks
9
watchers
254
prs
82
issues
16
releases
README
TwigStan is a static analyzer for Twig templates powered by PHPStan.
------
[!NOTE]
This project requires a significant amount of my time and effort to develop. If you find it valuable, please consider sponsoring me to support its continued growth and give it a star! ⭐️ Your support is truly appreciated! 🙏
Introduction
TwigStan uses Twig to compile templates to PHP code. It then optimizes the compiled PHP code slightly, allowing PHPStan to analyze it better. It then reports any errors back to the original template and line number.
The process consists of the following steps:
Template Context Collecting
We use PHPStan to search the PHP codebase for places where a Twig template is rendered. We collect the context that is passed to the template.
- ContextFromReturnedArrayWithTemplateAttributeCollector and ContextFromControllerRenderMethodCallCollector search for controllers that render a Twig template.
- ContextFromTwigRenderMethodCallCollector search for Twig\Environment::render calls.
Compilation
The TwigCompiler loads the template and converts it into a Twig AST (Abstract Syntax Tree).
The AST is optimized by running several Twig NodeVisitors. The AST is then compiled into PHP
using Twig's default compiler. The compiled PHP code is loaded and converted into a PHP AST.
We inject the previously collected template context as PHPDocs into the template.
On the PHP AST, we run various PHP NodeVisitors.
The goal is no longer to render the template but to analyze it.
This means we can remove elements that are not relevant to us.
The PHP AST is then dumped back into PHP code and saved to disk as a compilation result.
In the next steps, we will use these PHP files.
Flattening
The next step is to flatten the Twig templates. Templates can extend other templates.
The child template can choose to override blocks or not, and the parent template can also extend another template.
Variables set in a parent template should be available in the child template.
The TwigFlattener processes all the compilation results. It reads the Twig metadata
to identify the parent(s) and defined blocks. It takes the logic in the parent template (set variables, etc.) from the doDisplay
method and copies it into the child template's doDisplay block.
The same is done for the block hierarchy. It understands which blocks are overridden. The child template will eventually have all blocks defined.
While flattening, the original filename and line numbers are preserved. This is important because later on,
we want to trace errors back to their original location.
After the flattening process is finished, the PHP AST is again dumped to disk as a flattening result.
Block Context Collecting
Now that we have a flat template, we can analyze the context for every block.
We use PHPStan to run the BlockContextCollector.
This collector gathers the context before rendering every block or parent block call.
Scope Injection
Now that we know the Top issues
#220How to deal with PHPStan's extensions?15 comments · 2025-02-06#138Improve first-time experience4 comments · 2024-11-24#265Undefined array key "template"3 comments · 2025-04-15#246Unable to resolve path on Windows2 comments · 2025-03-04#221Bug: `{{ asset('logo/logo.svg')|slice(1) }}` causes Internal error2 comments · 2025-02-06#210Empty array passed to foreach2 comments · 2025-01-24#4Macros2 comments · 2024-09-09#264Undefined array key "context"1 comments · 2025-04-15
Discussions
#2980.2.30 comments · 2026-11-06#2910.2.20 comments · 2026-11-03#2880.2.10 comments · 2026-11-02#2860.2.00 comments · 2026-11-02
Latest release
0.2.8 0.2.8 2026-11-15What's Changed Support Symfony UX Twig components by @ondrejmirtes in https://github.com/twigstan/twigstan/pull/336 Benchmark analyses with Tally, and finish analysing templates that include themselves by @ondrejmirtes in https://github.com/twigstan/twigstan/pull/337 Fix nested embed context and baseline errors without a Twig line by @ondrejmirtes in https://github.com/twigstan/twigstan/pull/340 Full Changelog: https://github.com/twigstan/twigstan/compare/0.2.7...0.2.8