In the most recent post of this series (which is admittedly some time ago), I talked at length about Composer and its lock file.
I recommend reading the previous two articles because Composer is eventually going to play a role in this material that this and future posts are going to share. But if you opt not to catch up on them (or are already familiar with Composer) then the gist of the previous posts are, respectively, as follows:
I don’t recommend checking the vendor directory into your repository. That can become a huge directory later, and it can undermine the whole purpose of Composer.
Composer
The goal is to make sure that every one is running the same version of the dependencies of the project – not older versions, not newer versions – but the same version.
The Composer Lock File
With that said, there are numerous dependencies or packages that we can install that help us to make sure that we’re writing the highest quality code possible.
Sure, some of these may be in the form of something like coding standards, but those are really more rules than they are elements of writing high quality code (though I don’t think they should be left out of the discussion – just left out at this time 🙃).
Back to the tools in question: What are some tools that help write high quality WordPress code? I’m going to share a few of my favorites and them I’m going to talk about how we can run them all against a code base.
First, let’s take a look at static analysis with PHPStan.
Better WordPress Code with PHPStan
What’s Static Analysis, Anyway?
First, a few words about static analysis. Namely, what is it? It’s a mouthful, for one thing:
Static Code Analysis (also known as Source Code Analysis) is usually performed as part of a Code Review (also known as white-box testing) and is carried out at the Implementation phase of a Security Development Lifecycle (SDL).
Static Code Analysis commonly refers to the running of Static Code Analysis tools that attempt to highlight possible vulnerabilities within ‘static’ (non-running) source code by using techniques such as Taint Analysis and Data Flow Analysis.
Static Code Analysis via OWASP
Think of it this way: It’s a way to analyze a program for potential errors that you may not see when working on the code base.
That is, there are problems, bugs, security problems, that may be present but you can’t detect for a number of reasons (the least of which is that you’re too close to the code).
Over time, though, the development community has learned ways to analyze code, generate sets of rules, and build tools to help find exactly all of the above.
Static Analysis of WordPress-centric Code
And this is where PHPStan comes into play.
As mentioned, the goal of the package is to identify errors or bugs that exist in your code before your code is used by someone other than developers, highlight them, and give you the opportunity to fix them.
Because tools like this examine a code base (versus running the code), it’s not always possible to get a clear picture. This means we can get false positives.
More on this in a moment though.
If you’re interested in getting started with running PHPStan against your code base, it’s easy. After installing it, just remember to configure it so that it doesn’t look in the vendor
directory or, say, WordPress core.
Instead, have it examine your code.
Installing PHPStan
First, in your composer.json
file, add the following line in the require-dev
section:
"phpstan/phpstan": "^0.11.12"
Then run composer update
in your terminal.
Once it has been installed, you can run it against an individual file, a directory or a set of directories. If you’ve read my previous posts on code organization, then you know I’m a fan of keeping the majority of project source code in src
to you may run something like this:
$ vendor/bin/phpstan analyse src
This will generate output based on what the utility finds.
Remember earlier when I said that it may find things such as false positives? Here’s a more detailed run down of what you may see:
- Extra arguments passed to functions (e. g. function requires two arguments, the code passes three)
- Extra arguments passed to print/sprintf functions (e. g. format string contains one placeholder, the code passes two values to replace)
- Obvious errors in dead code
- Magic behavior that needs to be defined.
All of the above of straight from the repository.
This is where Rule Levels can make all the difference, though it may require a bit of tweaking to get it to a level that’s just right for your team or your project.
What About Analysis For WordPress?
Viktor Szépe shared this resource with me (something he’s authored, actually) and I think it’s something relevant and useful. The idea of the package is simple:
It solves all problems I had during analyzing code for WordPress.
Not bad, right?
Analyze Your Code
Regardless of your project, your code organization, or what level at which you run this particular utility, the point is always to improve the level of quality of we’re writing WordPress code.
Installing this as a Composer package and then running it against your src
directory is a step in the right direction.
As previously stated, I’m going to share a few other tools and I’m going to then share how to run them all against a code base prior to committing the code to a repository.
Note
If you have a problem attempting to set up the package, Dave Mackey contacted me with a similar issue and its solution.