Setup a WordPress development environment

by

Recently I had to setup a new development environment for creating WordPress themes. My requirements were as follows:

  • The theme should exist in a Git repository without core WordPress files
  • The local development should be undependent on the production database
  • Easy update on the production site from the Git repository

Basic needs for a developer and some convenience parts to make updating a breeze.

To handle my theme on the production site, I’ve chosen to use WP Pusher, a “WordPress like” way to install and update themes without the need of FTP transfers. To be able to use the plugin the theme must be available in a git repository. Here I’ve chosen GitHub but WP Pusher supports BitBucket and GitLab as well.

For the local hosting needs I’ve chosen to use the XAMPP environment from Apache Friends. This is a complete Apache web server with PHP support and a MariaDB database server. WordPress requires PHP and MySQL and luckily MariaDB is fully compatible with MySQL so we are all good.

The prerequisites to follow this walk through is to have Git installed on your system. You can skip the git parts if you don’t need this off cause.

Lets get to it.

Setup Git with the theme and WordPress core locally

First of create a new repository on your Git service. Keep it clean and empty for now, but copy the remote URL for later use.

Next up grab the the latest WordPress package from wordpress.org and save it in a location of your choice.

Extract the package to a working directory like ~/Projects/myWordpress and start up a terminal window / command prompt. Navigate to the themes folder in the extracted WordPress installation with cd ~/Projects/myWordpress/wp-content/themes on Unix/OS X or cd %HOMEPATH%/Projects/myWordpress/wp-content/themes on Windows and we are ready to initialize the new repository.

Clone your repository created earlier in to this folder with git clone URL and we are good to go.

There are different approaches to handling WordPress development with Git. This is to me the easiest one and keeps the repository clean from non-theme files like plugins and WordPress core files. Let me know if you got something even easier!

Let’s leave the repository for now and set up the server side of things.

Install XAMPP and setup virtual host

To install XAMPP and get it running with WordPress there are several steps to get done.

  • Install XAMPP
  • Optionally setup a virtual host
  • Create the database for WordPress
  • Setup WordPress

First things first.

Install XAMPP

Get the latest installation for XAMPP from Apache Friends download section. I’ve chosen to use the PHP 5.6.15 package as I trust this PHP version the most, but WordPress supports PHP 7 so go a head and grab the edge if you like.
Run the installer and follow the instructions. You only need to install Apache, MySQL, PHP and phpMyAdmin to run WordPress but feel free to select what ever else you like. When your done make sure the Apache server is running and navigate to http://localhost/. Here you will be presented with the welcome dashboard. This verifies the installation went good and we are ready to move on.

Setup virtual host

This step is optional and allows you to setup a virtual host for your WordPress site. This means getting another domain to hit than http://localhost/. I like to separate my projects into different hosts so here I will setup a host for http://myWordpress.localhost/.
If you don’t want this, skip ahead to the database creation step below.

On the XAMPP dashboard there is a guide on setting up the virtual hosts. I’ve taken the liberty to paraphrase the steps in here to keep the information together. Take a look on the HOW-TO guide for more information. (Note this link only works when you’ve got your XAMPP installation running)

Fire up a new terminal / command prompt and make sure you are logged in as an administrator. On OS X you need to enable the vhosts file. Go to the installation directory for XAMPP, typically this is /Applications/XAMPP. From here open the file httpd.conf in the etc/ subdirectory.
This is a LONG file, but use a search tool in your editor to find the line Include etc/extra/httpd-vhosts.conf and remove the prepended hash symbol (#). Save it and close the file.

If you are on Windows, this is not nessesary, just go to the installation directory for XAMPP, typically this is  C:\xampp.

Next up, open the httpd-vhosts.conf in the etc/extra/ subdirectory on OS X or  apache/conf/extra on Windows.

Replace the contents with the following snippet and copy your own directory to the root of the WordPress installation to the lines 6 and 8. Note the DocumentDoot value to the first host on line 2. This should point to the standard web site path. On OS X this is  /Applications/XAMPP/xamppfiles/htdocs/ and on Windows it’s  C:/xampp/htdocs/ if XAMPP is installed in the default directories.

To enable the changes is to restart the Apache web server in the XAMPP control panel.

So far, so good. Now XAMPP knows that there are two websites running on your Apache server. The XAMPP dashboard and your new WordPress installation, however if you navigate to http://myWordpress.localhost/ you get an error. We need to finish one last step to get you running. This is to map our custom domain to the proper IP address, that is your local host IP. So grab the terminal and open the file /etc/hosts on OS X or  C:\windows\system32\drivers\etc\hosts on Windows in your favorite editor and add the following line. Remember to open your editor as administrator on Windows.

You should now be able to access your newly created WordPress website on the address http://myWordpress.localhost.

Create a database

Before setting up WordPress we need to create a database.
Go to the XAMPP dashboard on http://localhost/ and click the phpMyAdmin link at to top. This is a database management site to handle setup and modifications of the database. Login with the default credentials for an XAMPP installation. That is user name  root and an empty password.
Create a new database at the left with a name of your choice. I call it myWordpress (A VERY meaningful and thought through name).

That’s that. Next stop setup WordPress

Setup WordPress

Done with all the setting up we are ready to use the WordPress setup pages. Go to your local WordPress site at http://myWordpress.localhost and follow the instructions. Use the database credentials and database name as setup earlier.
When done setting up you will be presented with the brand new local WordPress blog. Congratulations!

Additional setup

To allow installation of plugins in the local site without using FTP we can add a single line to the wp-config.php in the root of our installation.

While in this file you might want to set the WP_DEBUG flag to true to enable PHP error messages as well. This will become useful when starting to create your theme.

On OS X you might need to change the file permissions for the wp-content folder and subfolders to get it working. This can be done with the command chmod -R 777 wp-content/.

Production

When you got your theme running and committed to your repository, install WP Pusher plugin on your WordPress production site and point it to your repository. It will now download the files and make the theme accesseble like any other theme. For Open Source projects with a public repository, WP Pusher is free! Great stuff.

There you have it. You have now setup a complete WordPress development environment on a local computer and setup a git repository to handle versioning and collaboration on the theme files. Start working on your theme from scratch or a template. Check this cool post on 20 awesome templates from HONGKIAT.