Psalm or PHPStan?

My friend Garvin asked some time ago on phpc.social :

Today I finally played around with [PHP_CodeSniffer] and [PHP-CS-Fixer] and set up&configured them myself. It's still not really clear to me why two tools are needed for this, and why both are abbreviated in the same way. phpstan i can distinguish from that. And do I also want/need to deal with [Psalm]?

I have already written about PHP_CodeSniffer and PHP-CS-Fixer , but I have not yet responded on Psalm and PHPStan. I would like to make up for that now.

Psalm and PHPStan are tools for static code analysis. This has become an indispensable part of PHP development. As a developer of several static code analysis tools, I have witnessed this development first-hand and would like to share my experiences and insights from over two decades of working with these technologies. The journey from the early days of PHP 4 to the sophisticated analysis tools available today reflects not only the technical evolution of the language, but also the increasing importance of code quality and security in software development.

Fundamentals

Static code analysis examines source code without executing it to identify potential problems, vulnerabilities and quality defects. This technique enables developers to detect errors early on in the development process, when they are still relatively inexpensive to fix. Unlike dynamic analysis, which examines the running programme, static analysis works exclusively with the source code. It can therefore provide valuable insights even before the programme is executed for the first time.

In the days of PHP 3 and PHP 4, regular expressions were the only, albeit not particularly suitable, tool that PHP provided for analysing PHP code. With PHP 5, the tokenizer extension introduced a new approach: the result of lexical analysis, the first step in compiling PHP code, could now be used for developing static code analysis tools.

While most early tools were content with the tokens provided, the first tools began to implement complete parsers for PHP code in PHP. These more advanced tools performed their analyses on data structures that were already very close to abstract syntax trees.

However, the decisive breakthrough came with the release of PHP-Parser by Nikita Popov. This library provides a complete parser for PHP code implemented in PHP. With it, he created a robust and sustainable foundation for the development of professional tools for static code analysis.

The era of PHP_Depend and PHP Mess Detector

At the time of PHP 5, PHP_Depend and PHP Mess Detector were the dominant tools for static code analysis.

PHP_Depend analyses the code and generates detailed reports on various quality metrics, including coupling, cohesion, inheritance depth and cyclomatic complexity. PHPMD builds on PHP_Depend and acts as a front end for the raw data measured by PHP_Depend. It implements a variety of rules for detecting code smells and potential problems, including possible bugs, suboptimal code, overly complicated expressions, and unused parameters, methods, or properties.

The transition from PHP 5 to PHP 7 brought significant changes to the language syntax, which many existing static code analysis tools struggled with. Both PHP_Depend and PHPMD initially had difficulties with the new language features of PHP 7.

This led many developers, myself included, to look for alternatives or temporarily abandon static code analysis. The community was forced to develop new tools or fundamentally revise existing ones. Both PHP_Depend and PHPMD are now (more or less) actively maintained again and support modern PHP versions. However, the loss of trust during the transition period had a long-term impact on their acceptance.

PHAN

With the release of PHP 7 and its improved type system, there was a need for tools that could leverage these new features. PHAN was one of the first tools of a new generation designed specifically for the advanced capabilities of type checking. It was initiated by Rasmus Lerdorf, the inventor of PHP, which gave it special significance in the community from the very beginning.

During my short time with PHAN, I was impressed by its capabilities, especially in type checking. However, the tool was not yet fully mature in its early versions and occasionally had problems with more complex code structures. Configuration was sometimes cumbersome and the documentation was not yet comprehensive. Despite these limitations, PHAN demonstrated the potential of modern static analysis tools and laid the foundation for the next generation of PHP analysis tools.

Psalm

The discovery of Psalm marked a turning point in my work with static code analysis. I was particularly impressed by how flexibly different analysis levels can be configured: from the pragmatic setting "This is legacy code that I want to deal with as best as possible" to the requirement "I want to create modern, clean code here".

Psalm was the first tool I used to introduce a baseline for problems in my projects. This functionality allows you to document existing problems and focus on new ones. This makes integration into legacy projects much easier, as it would be impractical and economically unfeasible to fix all identified problems immediately.

During my years of using Psalm, the tool has continuously evolved and become an indispensable part of my development workflow. Psalm's configuration options are extremely flexible, allowing the tool to be adapted to the specific needs of different projects. The different error levels allow you to gradually increase the severity of the analysis, which is particularly helpful when integrating into existing projects.

The community around Psalm was active and helpful, and the documentation was comprehensive and well structured. The tool supported a wide range of PHP features and was regularly updated to support new language features.

PHPStan

At first, I ignored PHPStan because I was satisfied with Psalm. However, developments in the PHP community eventually forced me to reconsider my position. PHPStan quickly developed into a serious competitor and began to score points in areas where other tools showed weaknesses. As the development speed of the Psalm project slowed down and PHPStan gained momentum, it became increasingly difficult to ignore its advantages.

What really sets PHPStan apart is its extensive ecosystem of plugins and extensions. There are specialised PHPStan extensions for virtually every popular PHP framework and library that understand framework-specific patterns and APIs. This plugin ecosystem makes PHPStan an extremely versatile tool that can be adapted to different development environments. Whether Laravel, Symfony, WordPress or other frameworks: optimised extensions exist for most of them, which significantly improve the analysis. Thanks to this community-driven development, PHPStan delivers better results than generic tools in many specialised areas.

PHPStan is intuitive to configure and well documented, making it easy to get started. The different levels from 0 to 10 allow you to gradually tighten the analysis, which is particularly helpful when integrating into existing projects.

Psalm or PHPStan?

Every tool is the result of human development and inevitably reflects the views and philosophies of its creators in the way it works. This becomes particularly clear when several tools are used in parallel for the same task, such as static code analysis.

A vivid example is the simultaneous use of PHPStan and Psalm in a PHP project: both tools aim to improve code quality, but their rules can conflict when applied to the same code. Developers are then faced with the difficult task of satisfying both tools at the same time.

The seemingly objective nature of development tools is therefore deceptive. Rather, they are an expression of the subjective decisions of their creators and, when used together, can lead to considerable practical challenges that are difficult to solve with reasonable effort.

What now? And how?

Although Psalm is now being actively developed again, I am sticking with PHPStan because it optimally meets my current requirements and the extensive plug-in ecosystem offers considerable added value.

For developers who are new to static code analysis, I recommend starting with PHPStan, as it offers a good balance between feature set, ease of use, and community support. The investment in learning how to use it quickly pays off, as code quality and development efficiency improve significantly.

Ultimately, choosing the right tool depends on specific project requirements, team setup, and personal preferences. However, more important than choosing a particular tool is the decision to use static code analysis in the first place. The benefits, from early error detection to improved code quality and increased security, are so significant that no professional PHP project should be without it.

But regardless of whether you choose PHPStan or Psalm, successfully introducing static code analysis into a team requires careful change management and training. It is important to inform all team members about the advantages and functionality of the tools and to establish common standards for handling analysis results. Defining clear processes for handling false positives and adapting rules is essential for long-term acceptance.

Regular reviews of the tool configuration and the problems found help to continuously improve the analysis and adapt it to changing project requirements. Investing in training and workshops pays off in the long run, as well-trained developers can use the tools more effectively and achieve better results.

Outlook

The future of static code analysis for PHP looks promising: there are continuous improvements in analysis accuracy and user-friendliness. Machine learning and AI-based approaches are increasingly being integrated into static analysis tools, opening up the potential for even more accurate and context-aware analysis. These technologies could help to further reduce the rate of false positives and identify new types of problems.

The development of PHP itself, especially the continuous improvement of the type system, will also open up new possibilities for static analysis. With each PHP release, new language features are introduced that must be understood and utilised by analysis tools. Close collaboration between the developers of PHP and the developers of tools such as PHPStan or Psalm will be crucial to ensure that new features are supported optimally.