phpstan-forbidden-nodes brings configurable forbidden-node rules to PHPStan to ban debug calls and enforce architecture boundaries
phpstan-forbidden-nodes is a lightweight PHPStan extension that lets teams declare forbidden code patterns—such as var_dump or dd—so static analysis surfaces violations before they reach production.
A terse fix for a common PHP code smell
We’ve all shipped a stray var_dump or dd at some point. The author of phpstan-forbidden-nodes describes the same friction: a quick debug statement survives review, someone calls DB::raw in the wrong context, or a controller starts to call repositories directly and architecture rules slowly erode. Those small slips accumulate into hard-to-maintain code and occasional runtime surprises; catching them earlier is the whole point behind the extension the author built for PHPStan.
Why existing PHPStan options fell short
According to the project notes, PHPStan remains a powerful static-analysis tool, but creating and maintaining custom rules inside PHPStan is not trivial for many teams. The author framed the trade-offs this way: either invest time in authoring a bespoke PHPStan rule (which is time-consuming) or rely on simpler but limited mechanisms such as banning specific functions. phpstan-forbidden-nodes is presented as a middle path: a configurable extension that avoids writing PHP code for each custom restriction while giving more expressiveness than a basic banned-function list.
What the extension is designed to do
The extension was built to meet four concrete needs called out by its author:
- ban explicit debug functions such as var_dump and dd;
- restrict specific method calls in code where they do not belong;
- enforce architecture boundaries to prevent cross-layer violations;
- be configurable by developers and teams without writing additional PHP code.
These goals shape how the tool is configured and how it reports problems during static analysis runs.
How forbidden patterns are declared
The extension exposes a configuration-driven approach to specifying forbidden patterns. In the example from the project, the configuration defines a forbidden-node parameter that targets nodes of type Expr_FuncCall and lists the functions to forbid (for example, var_dump and dd). When PHPStan runs with the extension enabled and encounters one of the forbidden patterns, it emits a clear diagnostic such as: Forbidden function var_dump() used in App\Service\UserService.php:42.
That example demonstrates the extension’s primary mechanics: identify AST node shapes to match, provide the names or signatures to forbid, and surface precise file-and-line diagnostics that point developers to the offending location.
Practical uses for teams
The author highlights several practical rules that teams can enforce through this extension:
- no debug functions in production branches (preventing stray var_dump/dd calls);
- no direct database calls from controller code (preserving controller-to-service boundaries);
- preventing cross-layer violations that undermine architecture contracts;
- catching other unsafe patterns that a codebase wants to ban.
Because configuration is central to the extension, teams can express those constraints as data rather than new PHP code—lowering the barrier for adding new checks and for adjusting rules over time.
How the solution changes feedback loops
By converting these conventions into machine-checkable rules, the extension shifts feedback earlier in the development cycle. Instead of relying on manual code review to catch simple but consequential mistakes, a configured static-analysis run will flag violations automatically and with file and line references. The project’s sample diagnostic shows the extension’s goal: concise, actionable output that points developers directly at the offending call.
Who the extension is aimed at
The project targets PHP teams that already use PHPStan for static analysis and want finer-grained, configurable enforcement of project-specific rules without writing custom PHPStan rules. It is positioned for teams that need to prevent specific functions or patterns from slipping into the codebase and that prefer to manage such policies through configuration.
Repository and where to look for the code
The author maintains the extension in a public repository named rajmundtoth0/phpstan-forbidden-nodes on GitHub. The repository is presented as the canonical source for the extension and the example configuration shown in the project notes.
Developer ergonomics and configuration philosophy
A recurring design point in the project notes is the choice to favor configuration over code. That philosophy lowers the cost of adding or adjusting rules: instead of drafting a PHPStan rule class, a developer can add a new node pattern and a list of forbidden symbols to a configuration file. The example demonstrates this with function-call nodes and a small list of banned functions, but the same configuration-first mindset is meant to support broader pattern types and enforcement goals without requiring team members to author new PHP code.
Integration points implied by the design
While the project notes do not prescribe a specific integration workflow, the extension’s diagnostic output and configuration model imply straightforward integration into existing static-analysis runs. Teams that already execute PHPStan as part of local checking, pre-commit hooks, or continuous integration would be able to include the extension’s checks alongside other PHPStan rules and receive the same file/line diagnostics. The project’s example message—Forbidden function var_dump() used in App\Service\UserService.php:42—suggests the extension is designed to produce the same style of human-readable failure output teams already rely on.
Limitations and boundaries called out by the author
The project description explicitly warns against two common approaches that inspired the extension: writing full custom PHPStan rules (which is time-consuming) and relying on limited banned-function lists (which do not cover more complex patterns). The extension exists to provide a configurable, middle-ground solution, but the author does not claim it replaces every possible custom rule or that it covers every imaginable AST pattern out of the box. If a detail is not clearly established in the project notes—for example, how complex method-call restrictions are expressed or whether certain node types are supported—the safe approach is to consult the repository for exact capabilities.
Broader implications for PHP static analysis and team practices
Turning project conventions into static checks has concrete maintenance and cultural effects. When teams take repetitive or error-prone conventions—no debug traces in production, disciplined database access layers, strict layering between controllers and services—and encode them in machine-readable rules, the immediate benefits are consistency and earlier feedback. Over time, that consistency can reduce technical debt arising from incidental architecture erosion, and it can make code reviews more productive by freeing reviewers to focus on design and correctness rather than on catching basic policy violations.
The extension’s configuration-first model also influences who can maintain a project’s rule set. Non-PHP authors of policy—such as engineering managers or architects—can propose and tweak forbidden patterns through configuration changes, lowering the friction for policy changes. That approach can accelerate adoption of coding standards, since adding a new prohibited pattern becomes an edit to a configuration file rather than a development task requiring familiarity with static-analysis internals.
Developer implications and workflow considerations
Adopting a configurable forbidden-node extension shifts some responsibility to rule authors and maintainers. Teams must decide which patterns to forbid and keep the configuration aligned with their architecture principles. Because the extension produces standard diagnostics, it can be incorporated into the feedback chain developers already use: local lint runs, pull-request checks, and gatekeeping in continuous integration. The author’s example output suggests the extension’s messages are concise enough to be actionable in each of those contexts.
When to consider using this approach
Teams that repeatedly see the same classes of low-level mistakes—debugging calls making it into non-experimental branches, accidental direct DB calls in presentation-layer code, or creeping cross-layer dependencies—are the primary audience. The extension offers a lighter-weight alternative to writing bespoke PHPStan rules for each pattern and can bridge the gap between simple banned-function lists and the agility of configurable, declarative checks.
How to evaluate the extension for your codebase
Because the repository is available publicly under the name rajmundtoth0/phpstan-forbidden-nodes, evaluation can start by reviewing the project’s example configuration and by testing the sample forbidden patterns on a representative subset of the codebase. Teams should look for:
- the kinds of node shapes the extension can match (the author’s example focuses on function-call nodes),
- how forbidden symbols are expressed in configuration,
- the clarity of the diagnostic messages in the project output,
- and any examples or documentation the repository provides for more advanced patterns.
If those aspects meet a team’s needs, the extension can serve as a straightforward way to convert a convention into an automated check.
Practical questions addressed by the project notes
What the extension does: it enables teams to declare forbidden AST patterns—such as specific function calls—so PHPStan will report violations.
How it works in practice: configuration files declare the node type to inspect (for example, an expression-level function call) and the symbols to forbid; PHPStan then reports any matches with file and line information.
Why it matters: enforcing these checks at static-analysis time prevents simple but harmful mistakes from slipping through code review, preserves architecture boundaries, and helps teams maintain safer, cleaner code.
Who can use it: teams that already use PHPStan and want to add configurable, rule-based enforcement of project-specific forbidden patterns without authoring new PHP code.
When it is available: the project is maintained in a public GitHub repository under rajmundtoth0/phpstan-forbidden-nodes, which is the source of the extension and example configuration referenced in the project notes.
Next steps for teams interested in the approach
Teams that want to experiment should review the repository and the example configuration, try forbidding a small set of patterns that represent frequent mistakes in their codebase (for example, debug functions), and then iterate on the configuration as they discover additional patterns worth blocking. Because the configuration-first model is central to the extension, teams can evolve policies incrementally without needing to commit to larger static-analysis engineering efforts.
Looking ahead, configurable forbidden-node checks represent a practical compromise: they reduce the engineering effort required to codify rules while still enabling precise, actionable diagnostics from static analysis. For teams looking to preserve architectural boundaries, reduce accidental insertions of debug code, and make code-review time more productive, the approach articulated in the phpstan-forbidden-nodes project provides a lightweight path to more reliable enforcement of project conventions.
