Maintainable WordPress Development 1/3: Introduction, Structure, Tools & Automation

This is the very first of a total 3 blog posts from the “Maintainable WordPress Development” series that we’ll publish over the next two weeks. Through this and the next two blog posts we’ll show you how to build a WordPress project that is easy to build, maintain and extend while having multiple team members on board. We’ll show you the do’s and don’ts of WordPress development. This will hopefully help you to avoid unnecessary setbacks in the development process. Now let’s get down to the first maintainable WordPress development post!

Structure

The first step of every project is the initial project setup. When it comes to directory structure that you’ll use within that setup you basically have two choices. The first choice is to go with the default WordPress directory structure. The second is to go with a custom directory structure which can be a fully custom one or a pre-built open source one. So, which one should you go for? Well, to help you answer that question I’ll tell you what we did.

Initially we went with a custom directory structure. We did that to separate our custom code from the WordPress source code as much as possible. Pretty logical thing to do, right? It really is but after s0me time this started to bug us. There were a few use cases in which we failed to migrate the database to the production or staging server that was running the default WordPress directory structure. This was basically because we forgot to add one simple migration step. Now we had to enter four or sometimes even five steps instead of just two steps that are needed when working with the default WordPress structure.

OK, no biggie. Wrong migrations happen and they might even happen with the default WordPress structure. That’s indeed true. What we also found out is that there are some issues when running a multisite instance on top of the custom directory structure. We dug, and we dug even deeper until we found out that a simple update of the .htaccess solved those few issues we had. We also found out that the .htaccess file sometimes gets overridden by the WordPress itself (I really don’t know why this sometimes happens).

We once even accidentally pushed the modified .htaccess file to the production server which basically broke the administration area of the production site. Then, after so many issues we finally reverted back to the default WordPress directory structure which might have been a little bit messy. It turns out that it has it’s own advantages after all.

Tools

Now when we have the directory structure all covered we can talk about some useful tools that you can use as a part of your development workflow. When I say tools I’m actually talking about 4 categories of tools and those are: development tools, development scripts, development plugins and versioning tools.

Development tools

Development tools play a huge role in the development workflow (or at least they should) because the very purpose of those tools is to help you build your projects much better and much faster. Personally, I think that every team (or a freelancer for that matter) should pick the tools that fit their needs – nevertheless, here are some of the tools that we personally like to use:

• WP-CLI
• Node.js with NPM
• Gulp (coupled with few node modules/plugins like wp-cli wrapper, gulp-less, gulp-minify-css, gulp-uglify etc.)

All tools I’ve mentioned are free, open source and easily installable on almost any machine but they don’t serve their very purpose until they get implemented into the development workflow itself. So let’s talk a little bit about development scripts and how you can use them to basically automate parts of the development workflow by putting them to good use.

Development scripts

Development scripts are called from within the command line (terminal). We like to define all project specific scripts within the package.json file which is also used to define all devDependencies needed to run those very scripts. Here’s what that looks like:

Now, if you are more like us and you don’t like having gulp installed globally as well, you can easily add gulp as a development dependency and update the package.json file to look something more like this:

All scripts from the package.json file are invoked by typing the npm run <<script>> command (you must install them first, of course) and every script defined in that same package.json file should in fact “call” a certain tool (command) that should then preform a specific action within your project.

For example, build:less script, when called, executes a gulp task (defined within the gulpfile.js) that takes the LESS source files and compiles them into a single, production ready, CSS file. You could even create a prepare script that utilizes the WP-CLI tool (or a wp-cli wrapper module) to download and unpack WordPress source files within your project. We usually have following scripts implemented within almost all recent projects:

• prepare (executes wp core download and generates a wp-config.php file based on users input)
• build:all (executes gulp tasks that builds all CSS and JS assets)
• build:less (executes the gulp task that builds CSS assets)
• build:js (executes the gulp task that builds JS assets)
• watch (executes the gulp watch task that watches for file changes and acts accordingly)

Not only do these automated development scripts speed up the development of the project but they also make you certain that anyone else working on the project has everything he needs to work.

Development plugins

When it comes to maintainable WordPress development there are many plugins that help you develop well preforming themes and/or plugins. We usually like to use the following set of plugins when developing custom themes or plugins:

– Debug Bar (awsome for debugging in general)
– Force Regenerate Thumbnails (great for resizing/cropping of uploaded images to defined sizes)
– WP Migrate DB (easy database migration)

Since we’ve already talked about development scripts and development automation you can easily automate a download of those development plugins as well simply by creating a script that will download them for you and anyone else working on the project by, once again, utilizing the WP-CLI tool.

Versioning tools

As we come towards the end of the first maintainable WordPress development post it’s time to talk about versioning tools. Versioning tools help you build better projects because they allow you to quickly revert parts of the code back to a state in which they were in a certain point of time. They also allow you to cooperate with your team members without having the fear that someone will, somehow, override parts of your code. We like to use few different tools to do the versioning right and some of those are:

– Git
– SourceTree
– BitBucket
– JIRA

Now, how should you track and version your WordPress project? How to make your theme or plugin easy extend and maintain? What are those do’s and don’ts that I mentioned earlier? We’ll talk about those and few other useful things in our next post from the “Maintainable WordPress Development” series which will be published next Friday, so stay tuned!

That’s it for the first in the series of maintainable WordPress development posts. Got something to say? We’d love to hear from you.