WordPress Widgets: Starting with Standards

The purpose of this series is to start doing a deeper dive into working with object-oriented programming in the context of WordPress.

And since the WordPress Widgets API is one of the APIs that does use object-oriented practices, it’s a logical place to start. Further, it will give us some foundational techniques that we can use to apply to future work as we see how to build more object-oriented projects on WordPress in future series.

So far, we’ve covered the following:

  1. WordPress Widgets: An Object-Oriented Approach. The Widgets API provides a solid litmus test and example of how to get started with object-oriented programming in WordPress.
  2. WordPress Widgets: How to Detect Object-Oriented Programming. The goal is to arm you with everything you need to detect object-oriented practices.

If you’re not caught up, now’s a great time to do so. And if you have, then you’ll recall from the last post, we ended with the following note:

That is, we’ll revisit the WordPress Widget Boilerplate and I’m going to be refactoring it in its current state to adopt more modern PHP standards.

To begin updating the WordPress Widget Boilerplate to follow said standards, we need to do a few things:

  1. create a branch from the existing boilerplate,
  2. install code quality tools,
  3. ensure our IDE is properly set up,
  4. and begin refactoring the code to said standards.

And that’s what we’re going to start doing with this post.

Starting with Standards

If you’ve been a member of this site for some time, then you know that I prefer to use Visual Studio Code. If not, I have an entire set of articles devoted to how I use it (and thus how we’ll be using it throughout this series of posts).

And if you’re interested in coverage regarding coding standards, debugging, IDEs, development environments, and so on, check out The Independent WordPress Developer.

However, I’m assuming that if you’re reading this then you’ve read through the material above or you’re comfortable going through all of the material above.

With that said, let’s get started.

Downloading the Repository

The first thing you’re going to want to do is to clone a copy of the repository. I prefer to do this via the command-line.

Furthermore, I also think it’s worth doing so against the latest version of WordPress. If you don’t have a copy of Subversion’s trunk copy of WordPress, you can read how to set that up here; however, this is purely optional. You can follow along with the rest of this tutorial just fine with any version of WordPress you’d like.

To do so,

  1. Make sure that you are in the plugins directory of your WordPress installation
  2. And then enter the following commands into a copy of your terminal
$ git clone https://github.com/tommcfarlin/WordPress-Widget-Boilerplate.git

This will create a WordPress-Widget-Boilerplate directory in your plugins directory. You can navigate to it by simple typing:

$ cd WordPress-Widget-Boilerplate

The results of cloning the repository should look something like this:

Screen Capture on 2018-11-20 at 10-51-43.gif

Next, you need to make sure that you change to the develop branch that I’ve created. It’s really easy to do this. But before we do that, why not set the project up in Visual Studio?

Setting Up Visual Studio Code

The steps for setting the project up in Visual Studio Code are straightforward:

  1. Drag the directory for the Boilerplate into the IDE,
  2. Open the integrated terminal,
  3. Swap branches

Just as I’ve done above, I’ll provide a screencast on how to do all of this. Dragging a directory into Visual Studio Code should be easy enough, but swapping branches on the command line can be a little different.

First, setting up the project in Visual Studio Code:

Screen Capture on 2018-11-20 at 11-02-47.gif

Notice here that I also open the integrated terminal by hitting the CMD+P shortcut (I’m on macOS so your shortcut may be different). Then I enter the command to check out the develop branch.

Once you do this, your local repository should swap over to the develop branch. You can confirm that’s the branch off of which you’re working by typing:

$ git branch

And then review the content of the terminal. Strictly speaking, develop should be highlighted.

WordPress Widgets: Develop Branch

At this point, we’re going to be introducing a few new files into the project. At the end of this tutorial, you can form a pull to get everything that I’m about to document here. But because the purpose of what we’re doing is two-fold, it’s important to make sure we’re doing this in the proper sequence because the first step is something that I use in every single project for WordPress at this point.

So with that said, let take a look.

Composer and Code Quality

The first thing I like to do is set up a series of tools to enforce code quality. This is achieved by a variety of Composer packages. These include:

  • GrumPHP. A PHP code-quality tool. Do not underestimate the clarify and the degree to which this repository is full of information. If you ever get stuck with any of the other tools mentioned here, look through the documentation in this repository first.
  • PHP CS Fixer. A tool to automatically fix PHP coding standards issues.
  • PHP Parallel Lint. This tool checks the syntax of PHP files faster than serial check with a fancier output.
  • PHPMD. This utility takes a given PHP source code base and looks for several potential problems within that source
  • PHP Parser. A parser is useful for static analysis, manipulation of code and basically, any other application dealing with code programmatically.
  • Proxy Manager. This library aims to provide an abstraction for generating various kinds of proxy classes.

I want to be clear of two things:

  1. The above tools are the bare minimum that I use, and you’ll likely see me use additional tools in the future,
  2. the tools above will help enforce code quality rules before checking code into a repository. It’s meant to compliment the set up in your IDE.

To get these tools set up and running within the project, we’ll need to create a composer.json file that looks like this:

Remember, you can pull this down manually at the end of this post. If, however, you’d like to follow along, feel free to manually do this. I’d never want to discourage you from that. 🙂

Once you’ve created the composer.json file, you’ll want to make sure that you run the following command from the terminal:

$ composer install

This may take some time; however, once it’s done, you should be presented with the following message:

Watch out! GrumPHP is sniffing your commits!

To give it a dry run, enter the following command in your terminal:

$ vendor/bin/grumphp run

Depending on how you’re working with the project, you may see output that looks something like this:

Screen Capture on 2018-11-20 at 11-53-58.gif

But there’s more work to do. Namely, we need to:

  • update our .gitignore file,
  • introduce configuration for GrumPHP
  • introduce configuration for PHPMD,
  • introduce configuration for PHPCS,
  • eventually, restructure the boilerplate’s directory structure.

Everything up to the final step, we’re going to aim to do in this post.

Updating The Ignore File

First, we don’t want to commit the vendor directory or the composer lock file. These can be generated whenever a user downloads the directory. They can easily fall out of sync and they add enormous size to the project’s directory.

To that end, your gitignore file should look like this:

This tells the plugin to ignore anything except what’s in the root of the plugin directory (and some of the eventual directories we’ll create) along with some basic files that we’re used to seeing in WordPress installations.

Some of what you see, such as wp-config.php or wp-content/backups you’re never likely to see in the context of a plugin, but these are standard WordPress ignore directives that I like to keep handy.

You’ll notice that I’ve also added vendor and the composer lock file to the bottom of the file.

Configure GrumPHP

GrumPHP can do a lot, and if you spent time perusing the repository before reading this far, then you likely know that; however, I’ve going to keep it as lean as possible, so it provides the instructions it needs for the tools we’re using and nothing more.

In short, this says to run a variety of checks for:

  • security,
  • composer,
  • JSON,
  • XML,
  • Yaml,
  • PHP,
  • PHPCS,
  • PHP Parser,
  • PHPMD,
  • and more.

Once we’ve completed setting everything else up, I’ll be sure to show you how all of this fits together. But first, let’s finish configuring the rest of our utilities.

PHPCS

This uses two separate files – a dist file and an XML file – each of which serves different, though very helpful purposes.

The first file, php_cs.dist which you’ll see in the repository by the end of this post, provides a header that’s applied to all PHP files in our project. It also enforces some different rules that improve the code quality.

The rules are self-explanatory, and you can see what it will enforce simply by looking through each of the rules that are defined.

Next, you’ll also want to create the XML file to complement the above file. You’ll note that in the file I’m providing, this is what I use for my work at Pressware. Furthermore, it also acknowledges the tests directory.

At this point, we don’t have any unit tests written, but should you opt to introduce them into your widget, this will be ready to handle them properly.

There’s only a small set of configuration that I specify here, but I’ve found it to be more than sufficient for my needs thus far. As I discover more or opt to use more, I’ll certainly update the content in future posts.

Configure PHPMD

And finally, we need to configure the PHP Mess Detector (or PHPMD). Luckily, this uses an XML file that will use rulesets as defined in the package installed by Composer. All we need to do is reference the rule in the configuration file.

Secondly, we’ll also provide a small exclusion for a ShortVariable name as you’ll see in the following gist:

And once all of these are in place, we should be able to run GrumPHP again, from the command-line, and have a slightly different set of results.

Running GrumPHP Again

Enter the following into your terminal:

$ vendor/bin/grumphp run

And you should see something like this:

Screen Capture on 2018-11-20 at 12-50-27.gif

Different results than the first time, huh? This is because we’re violating some rules and standards that are a modern part of PHP and object-oriented development.

And that’s what we’re going to clean up in the next post.

Coming Up

So where’s the object-oriented nature of this coming from? Up to this point, we’ve been talking about using the Widgets API as an object-oriented model for writing object-oriented code in WordPress.

Some of what we’ve done thus far has been exactly that (by talking through its principles, seeing how its laid out, and more).

But as I mentioned at the start of this post, laying code quality tools first provides us with a foundation we can use as we refactor the boilerplate (which we clearly need to do given the amount of red shown by GrumPHP).

And that’s where we’ll start in the next post in this series.