WordPress theme development with Vagrant on OS X

Developing WordPress themes requires you to have either remote machine with the needed software or installing e.g. PHP and MySQL to your local machine. Although setting up the development environment (LAMP stack) in OS X is quite easy there’s also better option, to separate it from your machine and make it more like it’s on some hosting provider. And for that it was time to get to know how Vagrant works and how to utilize it for WordPress theme development on OS X. Also this way you can make separate environments for different projects. Here’s short article to get you started.

In short: We setup Homebrew to install packages, Virtualbox will be used to run an Ubuntu Linux virtual machine and then we will use Vagrant to start, stop and build the virtual machine from Vagrantfile.

Setting up Vagrant for WordPress development

Step 0: Install Homebrew

We will use Homebrew to install the needed packages on OS X. Homebrew is the missing package manager for OS X.

$ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Step 1: Install VirtualBox

You can install Virtualbox manually or by using Homebrew.

$ brew cask install virtualbox

Step 2: Install Vagrant

Vagrant is software for creating and configuring lightweight, reproducible, and portable virtual development environments. It can be seen as a wrapper around virtualization software such as VirtualBox and around configuration management software such as Ansible, Chef, Salt or Puppet. Vagrant essentially builds virtual images from references (boxes) of a type of operating system with applications and dependent software.

You can install Vagrant from Vagrant site or by using Homebrew.

$ brew install Caskroom/cask/vagrant

Step 3: Vagrantfile for WordPress environment

To get started quickly we want to start with some premade Vagrantfiles and there are multiple choices for WordPress development.

One good choice could be WordPress Theme Review VVV which also installs Theme Unit test data and other plugins to test your theme. Other simple option is to use Vagrantpress which is a packaged development environment for developing WordPress themes and modules.

  • Clone the project, $ git clone https://github.com/chad-thompson/vagrantpress.git
  • Run $ vagrant plugin install vagrant-hostsupdater from command line
  • Rename the vagrantpress to the name you want for your project.
  • Navigate to the directory you just renamed.
  • Run the command $ vagrant up from the directory. It will ask your password to setup the hostname.
  • Open your browser to http://vagrantpress.dev

Working with the environment

To log in to the local WordPress installation: http://vagrantpress.dev/wp-admin/. The username is admin, the password is vagrant.

Your WordPress installation files can be seen in the directory you created for the VagrantPress.

You can access phpMyAdmin: http://vagrantpress.dev/phpmyadmin/ with username wordpress, password wordpress.

Using Vagrant

Using Vagrant is quite simple and there’s nice Getting started guide. In short there’s couple of commands you need. Also the virtual machine is located on your home directory under ~/.vagrant.d/boxes.

To start or resume working on any project, to install every dependency that project needs, and to set up any networking and synced folders, type this in your project directory.

$ vagrant up

See your Vagrant virtual machines’ status.

$ vagrant global-status

You can ssh to your project’s machine running in Vagrant.

$ vagrant ssh

You can also ssh to Vagrant’s Linux. The password is vagrant as also is the root password.

$ ssh vagrant@127.0.0.1 -p2222

When you’re done working for the day to suspend your VM:

$ vagrant halt

When you’re done playing around, you can remove all traces of it. Note: it also removes all the changes you made to the virtual machine, like your WordPress settings and data.

$ vagrant destroy.

If you ever have any issues with the VM, you should try to provision it with puppet again.

$ vagrant reload --provision

As Vagrant is running the virtual machines with Virtualbox you can also manage and see their status by starting Virtualbox GUI. Or using following commands.

$ VBoxManage list runningvms
$ VBoxManage list vms
$ VBoxManage controlvm <uuid> poweroff
$ VBoxManage unregistervm <uuid>

Auto-expand WP-Syntax code blocks

Hilighting code blocks in Worpdress blog posts can be achieved with different plugins and one of them is the WP-Syntax plugin which uses GeSHi source code highlighting and supports a wide range of popular languages, highlighting with or without line numbers and maintains formatting while copying snippets of code from the browser. The plugin highlights code using HTML’s <pre> tag, e.g. <pre lang=”java” line=”1″> for Java and line numbers starting at 1.

Source code highlighting makes it easier to read examples but sometimes if your layout isn’t 900+ pixels wide, you may end up with horizontal scrollbars for wider code blocks as you can’t always make it 80 characters. But fortunately you can make the plugin auto-expand the code block when hovered over. You just have to edit the plugins code a bit as Derek MacDonald explains.

For some reason the code to auto-expand the block when hovered over has been commented out in the plugin and to enable it you’ll have to edit three files:

wp-syntax/wp-syntax.php
In method enqueueScripts(), uncomment the line that invokes wp_enqueue_script() so wp-syntax.js will be loaded.

wp-syntax/css/wp-syntax.css
Ensure the overflow, overflow-x, and overflow-y properties of class .wp_syntax are set to hidden.

wp-syntax/js/wp-syntax.js
It might be better to remove the box-shadow CSS property added during the mouseover event because it doesn’t look good in most designs.

The mouseover/mouseout expand/collapse events will be immediate with no delay.