Five Tools for Writing High Quality PHP
The PHP ecosystem has grown and matured into a wonderful place to work. At Help Scout, we use PHP for a wide variety of projects, and we use several excellent tools to help us deliver high quality code.
In this post, I’ll share some of my own favorite tools that you can use to help ensure that you’re shipping high quality and maintainable code.
PHP Mess Detector (PHPMD)
PHPMD can be used to locate overly complicated code and potential bug sources. This is a great way to identify areas of a project that could benefit from refactoring. You can choose to examine code with a combination of rules. In particular, the code size rules can be helpful in locating convoluted code.
In the following example, we are looking for code size violations in a directory of transformers. We find a method with high complexity that is a great candidate for refactoring. This kind of complexity is a spot where bugs can frequently be found hiding.
Cyclomatic Complexity can indicate that it’s time to refactor.
In addition, PHPMD can be used as part of a continuous integration system to prevent developers from committing convoluted code. It has exit codes that make it a great candidate for use in automated code quality checks.
PHP Copy/Paste Detector (PHPCPD)
PHPCPD can be used to locate duplicate code. When a project has code that has been copy+pasted there’s always a chance a bug will be introduced when the logic is updated in one place and not another. Using PHPCPD is a great way to locate logic that exists in multiple places. It can also be used to alert you that you’ve created something that may need to extracted into a new component.
In this example, we can see that we have copied a method into a new class and that we could extract it with a trait or perhaps an abstract class.
Duplicate logic is a bug waiting to happen.
PHP Lines of Code (PHPLOC)
PHPLOC is a great way to quickly measure the overall size of a project. It’s very useful for getting a handle on the issues that an existing project may face. Here’s an example report:
This has been truncated, there’s more metrics in a full report!
There’s a lot going on in this report, and it’s useful to examine just a few of these items. The Average Class Length is a great way to see if a project has architectural problems with classes that have grown unwieldy, and the Cyclomatic Complexity report can tell us if we’ve got a lot of convoluted code. It’s also nice to know how many Non-Comment Lines of Code (NCLOC) you actually have in a project.
The raw numbers for these metrics are useful enough to indicate the general state of a project, but they are more useful when used to monitor trends. To accomplish this, PHPLOC can be used to generate a CSV file. You can then collect these CSV files over time to build trend reports. There are plugins for Jenkins and other CI environments that can be used to chart the values from these CSV files.
These trends can be enormously valuable for monitoring the accumulation of tech debt and the overall growth of a project. For instance, this can be used to watch for an increase in average complexity and know that perhaps the project has accumulated too many quick fixes and that it may be time to focus on quality.
PHP Code Sniffer (phpcs, phpcbf)
While the previous tools are about analyzing code, the PHP Code Sniffer is a rule based code sniffer and formatter. It can be run with preconfigured standards like PSR2 or with custom rules. In the following example, phpcs will detect a missing doc comment in one of our command classes.
At Help Scout, we make extensive use of phpcs on both the command line and with a PHPStorm integration. It’s easy to develop custom rules, and we’ve published our code standards.
Many of the rules that you write can also be used with the accompanying phpcbf tool to automatically format code. The phpcbf tool can handle many common tasks such as converting tabs to spaces and ensuring proper case of php constants like true and false.
Overcommit Git Hook Manager
Overcommit allows you to manage git hooks from within source control. Overcommit is flexible enough to support a wide variety of tools across many projects. It’s just as relevant to a Java project as it is to a PHP project. It’s a great way to add automated checks during git operations and to ensure that all project developers have easy access to common tooling.
Here’s a few of the things we use Overcommit for at Help Scout:
Preventing code with merge markers from being committed
Preventing invalid php from being committed
Protecting the master branch from pushes
Enforcing our code style rules with phpcs
Linting our YAML files
The FixMe check warns if you leave a //FIXME comment in your code.
Summary
PHP has come a long way from the wild west days of CGI. It is now part of a modern ecosystem and the accompanying development and static analysis tools allow us to manage quality in new and exciting ways. I urge you to explore these five tools along with other PHP static analysis tools like PHPStan and Infection and to think about how code analysis can play a part in your development cycle.
