PHP Upgrades: Block regressions with PHPStan

Photo by Ron McClenny on Unsplash

Often when people think of PHPStan they typically think of improving Type Coverage. That is really only a small part of what PHPStan is capable of. In this article we’ll learn how to use it to stop upgrade regressions.

What is an upgrade regression?

An upgrade regression is when you have functionality in your application that you wish to move away from. This could be code within your application or code within a dependency you’ve installed.

Often when trying to perform upgrades we can’t do it all in one go. Instead we have to make small incremental changes. Equally as we do this we don’t want other developers to continue to use deprecated methods and properties. In this situation those new method calls etc. are regressions in your progress to upgrade your application.

Installing PHPStan and the Deprecation Rules extension

To start tackling upgrade regressions, the first step is to install PHPStan if you haven’t already. You can install it via Composer:

composer require --dev phpstan/phpstan

Next, you’ll want to add the Deprecation Rules extension, which specifically helps track the usage of deprecated methods, properties, and classes in your codebase:

composer require --dev phpstan/phpstan-deprecation-rules

Once installed, you can configure PHPStan to use the deprecation rules by adding it to your phpstan.neon configuration file:

includes:
    - vendor/phpstan/phpstan-deprecation-rules/rules.neon

Running PHPStan with this setup will now flag any deprecated methods, properties, or classes in your codebase. This is an essential step in preventing upgrade regressions as you’ll be notified when deprecated code is used. You can then refactor those instances to ensure your application moves towards newer, supported functionality.

Go further with the Disallowed Calls extension

While the Deprecation Rules extension catches deprecated code, the Disallowed Calls extension offers a way to block specific function calls, method calls, or even entire classes that you no longer want to allow in your codebase. This is particularly useful for more fine-grained control over your code such as code that does not have a deprecation warning.

composer require --dev spaze/phpstan-disallowed-calls

After installation, you’ll need to configure it in your phpstan.neon file. Here’s an example of how you can disallow certain method calls or functions:

includes:
    - vendor/phpstan/phpstan-deprecation-rules/rules.neon
    # add the extension
    - vendor/spaze/phpstan-disallowed-calls/extension.neon

parameters:
    # You can see more example at https://github.com/spaze/phpstan-disallowed-calls/blob/main/docs/custom-rules.md
    disallowedMethodCalls:
        -
            method: 'PotentiallyDangerous\Logger::log()' # `function` is an alias of `method`
            message: 'use our own logger instead'
            errorTip: 'see https://our-docs.example/logging on how logging should be used'Begin writing your own rules
    disallowedFunctionCalls:
        -
            function: 'var_dump()' # `method` is an alias of `function`
            message: 'use logger instead'

This extension is pretty comprehensive meaning you’ll be able to cover the majority of scenarios. Of course there might be some situations that don’t work and for that the best thing is to start learning to write your own rules.

This is something we’ll get into in another article.

Conclusion

Using PHPStan to catch upgrade regressions is a smart way to make the upgrade process easier, especially in large development teams. Applying PHPStan to your continuous integration setup