Development using Roots


As a matter of fact, if you use Vagrant + puppet to set up your Virtualbox VM on Windows, you will get to use all of your Windows tools to work with code hosted on your virtual linux server. It works by utilising the shared folders features of Virtualbox, which allows you to access the files in the VM through the normal Windows filesystem.

That may sound mad, but it is certainly worth looking into.

I meant that mostly because way more tools are available, and specifically made, for Linux + Mac.

About version control, it sounds like you still write code locally, then FTP the file to a remote server. Correct?

You can still download the entire codebase to your local computer (if you don’t already have it) and create Git repositories for them. Then at least save the file locally, commit the changes to your repository, and then FTP the file up remotely. Then at least you’d still have a proper version control repository with commits for each change.

Or are you actually just editing a file straight off an FTP server and when you save it, it sends it back to the remote server? Because you should get away from that ASAP if that’s the case.

We’re going to be releasing a full WP stack setup including Vagrant for a Linux (Ubuntu) VM soon. And us Roots people have been using it for a while writing code locally. The folder/files are shared with the VM so it’s all seamless. Technically, it’s also developing locally as well but the entire dev setup is on the VM other than our local code editor. And it’s not mad at all. Actually a great way of doing things.

Sounds great. Seems like you guys are really taking roots to the top. Thanks for all of your efforts and thanks for sharing such a great tool :wink:

Hi guys,

I’m new to roots here. I’m trying to wrap my mind around as to where it shines and how to use it to maximize the benefits.

Is the base.php everything here? Do we have to use the theme wrapper concept? Is it the bread and butter here?

Though, I do get the reasoning behind the theme wrapper concept from a computer science point of view, but I’m finding it hard to justify it in use. I think it causes more confusions than it solves… Neither scribu’s nor Joel Kuzmarski’s posts help, well for me at least.

WP template hierarchy is already pretty good. With the get_header and get_template_part, we are almost there. Why seek perfection here… I don’t get it., Please help me clarify as to why it is needed to place this extra layer on top of WordPress template hierarchy?

And finally, is there a way to cancel it and make the roots work traditional way that is no theme wrapping… and if that’s possible, does that really defeat the purpose of using Roots for development at the first place and I may be better of working with another HTML5 BP + Bootstrap framework?

Thank you

1 Like

The wrapper concept totally does your head in at first. It took me weeks to work out what was happening, but now I really love it. It means much cleaner code and funnily enough is easier to work with. However I totally feel your pain.

The problem for me was that I hadn’t got to grips with the standard WordPress template hierarchy which made getting my head round how Roots worked harder.

I don’t know whether this will help you or anyone else, but here are some notes (quite a bit taken from the WP docs as well) that I made up whilst I tried to get my head round it all…

Standard WordPress set up

Normally WordPress has the following template files:

  • List item
  • style.css
  • header.php
  • index.php
  • sidebar.php
  • footer.php
  • single.php
  • page.php
  • comments.php
  • 404.php
  • functions.php
  • archive.php
  • searchform.php
  • search.php

WordPress uses the Query String (which it gets from the URL of the current page on the website) to work out what template file or template files to use to generate the page.

Firstly WordPress works out what type of page the current page is (i.e. is it a posts, archive, page, category or other page)

WordPress works out what template page or pages to use based on something called the Template Hierarchy.

WordPress firstly checks to see if it can find the most specific template file for its needs and if not it falls back to the default. For example it may check the category ID, slug, taxomony name or other criteria.

How WordPress checks depends on the type of page being requested. For example if the page being requested is a blog category page it will try the following:

  1. It checks to see if there is a category template file for the current category. For example if the current category has an ID of 4, it will check to see if category-4.php exists
  2. If not it will check to see if the generic category template file, category.php exists.
  3. If that doesn’t exist it will check to see if the archive template exists- archive.php
  4. If that doesn’t, WordPress will fall back and use the default index.php

Here are the queries depending on page type:

Front Page

  1. front-page.php (if doesn’t exist, falls back to…)
  2. index.php

Home (Blog) Page

  1. home.php (if doesn’t exist, falls back to…)
  2. index.php

Single Post

  1. single-{post_type}.php. If you are using custom post types you enter the slug of the custom post type- for example if the custom post type is “events”, this would be single-events.php (if doesn’t exist, falls back to…)
  2. single.php


  1. custom page type (The Page Template assigned to the Page. You can create your own page templates (page-templatename.php for example) and select these on the edit page section). At the top of the page template you should put the template name in comments: /* Template Name: Magazine */ (if doesn’t exist, falls back to…)
  2. page-(slug).php* (if doesn’t exist, falls back to…)*
  3. page-(id).php (if doesn’t exist, falls back to…)
  4. page.php* (if doesn’t exist, falls back to…)*
  5. index.php

Category (“Category” is an example of a “taxonomy”)

  1. category-(slug).php (if doesn’t exist, falls back to…)
  2. category-(id).php (if doesn’t exist, falls back to…)
  3. category.php (if doesn’t exist, falls back to…)
  4. archive.php (if doesn’t exist, falls back to…)
  5. index.php

Tag (“Tag” is an example of a “taxonomy”)

  1. tag-(slug).php (if doesn’t exist, falls back to…)
  2. tag-(id).php (if doesn’t exist, falls back to…)
  3. tag.php (if doesn’t exist, falls back to…)
  4. archive.php (if doesn’t exist, falls back to…)
  5. index.php

Custom Taxonomies

  1. taxonomy-(taxomony)-(term).php (if doesn’t exist, falls back to…)
  2. taxonomy-(taxomony).php (if doesn’t exist, falls back to…)
  3. taxonomy.php (if doesn’t exist, falls back to…)
  4. archive.php (if doesn’t exist, falls back to…)
  5. index.php


  1. archive-(post_type).php (if doesn’t exist, falls back to…)
  2. archive.php (if doesn’t exist, falls back to…)
  3. index.php


  1. author-(nicename).php (if doesn’t exist, falls back to…)
  2. author-(id).php (if doesn’t exist, falls back to…)
  3. author.php (if doesn’t exist, falls back to…)
  4. archive.php (if doesn’t exist, falls back to…)
  5. index.php


  1. search.php (if doesn’t exist, falls back to…)
  2. index.php (if doesn’t exist, falls back to…)

404 (Page Not Found)

  1. 404.php (if doesn’t exist, falls back to…)
  2. index.php (if doesn’t exist, falls back to…)

Here are the main template files that usually come with a theme excluding headers, sidebars and other sections of pages:

  • 404.php
  • author.php
  • base-front-page.php
  • base.php
  • category.php
  • front-page.php
  • index.php
  • page-custom.php
  • page-sample-page.php
  • page.php
  • single.php
  • search.php

As well as the above there are sections of pages that the above pages can use to put together the page:

  • header.php
  • footer.php
  • sidebar.php
  • searchform.php

Finally there are some special files that need to be included:

  • style.css (this gives WordPress the name and details of the theme. It can also be used for CSS styles)
  • functions.php (special functions for the theme to use)

As well as the above you can now put in special template files that the template hierarchy can use for specific pages. For example a template for a specific category “category-(slug).php”


WordPress usually puts all of the code and content into these template pages and fetches the header, sidebar and footer from the header.php, sidebar.php and footer.php files. Roots does away with all of that and uses base files to give the template structure. This means you can have different pages with different headers and footers. This changes the way the WP template hierarchy works slightly.

If the current page is the front page, WordPress would normally check for the front-page.php template. However, Roots runs some code that checks to see if there is a “base” file for that template. In this case it is looking for base-front-page.php. If that doesn’t exist it will look for base.php. The base file includes the header and footer and checks to see if the sidebar should be outputted, but actually you can get the base.php file to output whatever you like.

For example…

Front Page

  1. base-front-page.php (if doesn’t exist, falls back to…)
  2. base.php

Home (Blog) Page

  1. base-home.php (if doesn’t exist, falls back to…)
  2. base.php

Single Post

  1. base-single-{post_type}.php. If you are using custom post types you enter the slug of the custom post type- for example if the custom post type is “events”, this would be single-events.php (if doesn’t exist, falls back to…)
  2. base-single.php
  3. base.php

I hope that makes it clearer. It helped me…

(edited to fix formatting)


@iagdotme: thank you for taking the time to post your reply. I appreciate it. I read your reply line by line. Even though I knew about the WP template hierarchy, reading it once more was nice.

Let me get to the ROOTS part.

with roots… you can have different pages with different headers…

But this is also possible in a good old header.php which is brought in by a get_header() call embedded in index/single/archive/you-name-it.php, In the header.php, you could easily include a header-X.php or a header-Y.php depending on the whatever the situation is. By simply going thru a one-and-only header.php ( or footer.php for that matter), one can easily determine what’s happening…

for example, the following code, when placed in a (non-roots) functions.php, would give you the name of the template file;

add_filter( 'template_include', 'var_template_include', 1000 );
function var_template_include( $t ){
    $GLOBALS['current_theme_template'] = basename($t);
    return $t;

function get_current_template( $echo = false ) {
    if( !isset( $GLOBALS['current_theme_template'] ) )
        return false;
    if( $echo )
        echo $GLOBALS['current_theme_template'];
        return $GLOBALS['current_theme_template'];

Then, header.php would easily & clearly tap into that information thru something like this

switch ($GLOBALS['current_theme_template'] ){
	case  'home.php':
		include ('header-home.php');
		return;  //this call allows PHP to exit the include file right very here...
	case  'single.php':
		include ('header-single.php');
		return;  //this call allows PHP to exit the include file right very here...
	case  'archive.php':
		include ('header-archive.php');
		return;  //this call allows PHP to exit the include file right very here...
		//go on ( meaning stay in this header.php and output what will come after... ) 

//regular header goes here...

So, if it is the layout flexibility, doesn’t the above code achieve it in a more straight forward way that does not require the understanding of this? image

I am still not getting as to how the theme wrapper concept would simplify the work flow. But I haven’t quit yet. :slight_smile:

1 Like

Sorry, missed your comment. Thanks for this- makes sense!

I do develop locally. I make the changes in a code editor (either Notepad++ or Dreamweaver) and then FTP it up and take a look on the live or dev site. So I could use version control. Dreamweaver has one built in but I don’t like the look of it. I would love to use git because I really like the way GitHub from what I’ve seen.

I think I kind of understand…
However (forgive my ignorance) what do you mean by a “full WP stack setup”? Do you mean all the WordPress core code as well as the site? What is Vagrant?

I’m not against the idea of running Ubuntu in a virtual machine using Virtual Box, but I’d have to see the advantages. What code editor do you use on Linux?

Is the whole site (including database) stored locally? If so how do you then push it to the dev or live site? How do you make sure all the paths are correct? What happens if the main site uses SSL?

I’ve not got into using LESS yet, but I expect developing locally would help this. Presumably when you upload/push the new code to the dev/live site your less code is compiled into CSS?

Wow, this still sounds very mystical to me!

I assumed you knew a lot more about the WP theme hierarchy than me, but I thought other people might find it useful.

I suppose I haven’t actually answered WHY the Roots theme wrapper is a good thing, only a little more about how it works. The diagram you included did my head in when I saw it, but slowly I started to get my head round it particularly reading the various comments in the old Google group.

Why does Roots do this? I am hoping someone else more qualified than me can answer that…

  1. By “full WP stack setup” I mean a virtual machine that has nginx, php, php-fpm, mysql, and WP itself all setup. Using Vagrant, all you do is type “vagrant up” and you have a complete virtual machine with WP already installed and your theme loaded. Vagrant is basically just a tool for easy VirtualBox VM management specifically made for development environments.

  2. As I said before, with a setup like this you can use your local editor on Windows. The folder (WP site) you’re editing is kept in sync on the virtual machine all seamlessly.

  3. Everything is local. Usually you deploy by cloning your Git repo on your remote host and just pull down changes. Not sure why SSL on the live site would make any difference. You wouldn’t use SSL locally.

  4. Correct. Any pre-processor like LESS should ideally be run as part of the deploy process.

Thanks for clarifying what “full WP stack setup” means. I’ve just noticed you mention nginx. I’ve looked up and it seems that some people are using this as a replacement to Apache. There might be an advantage to using it, but I am stick with Apache for now since my Virtual Server uses that (under cPanel). Is that a problem?

So, I think I get that the Virtual Machine can access folders on my Windows computer and so Vagrant would be able to “do it’s stuff” on the files on the VM. Would I be running version control (git) on my Windows installation or on the VM?

I mentioned SSL because I was wondering how I could test locally if the dev and live sites had SSL (I use the Better WP Security) plugin. If the local and live sites were effectively clones of each other, wouldn’t the local site try and use SSL and fail? Also I use other plugins such as EWWW Image optimizer which uses PHP libraries to optimise images on the fly. These probably wouldn’t work locally.

Nothing is a problem :slight_smile: It’s all up to you. But obviously if you wanted to use our Vagrant setup for example, it would only support nginx by default.

You’d be running version control locally on your Windows host.

It gets a bit tricky with plugins for different environments. If you were using a virtual machine, there’s no reason you couldn’t have the EWWW Image optimizer working as well. SSL is a different story and you’d want it disabled in dev.

Scott, I have a related question about repositories. I have a lot of WordPress sites. I hate to keep all those copies of WordPress itself. So do you just Git the theme directories and custom plug-ins? All of wp-content? Or the entire site?


Thanks. Getting plugins to work both locally and remotely might be tricky. Is possible with your Vagrant set up to not overwrite certain plugins and their settings?

Would it be possible to use Apache with your set up? And if so, would it be possible to provide instructions for that as well? I am sure there will be many people still using Apache.


Ideally you have a Git repository per site including everything EXCEPT the WP core itself. Just tracking your theme and plugins isn’t really ideal because you might be missing things like wp-config.php and a proper folder structure. Currently the most popular way is probably The WP core is a separate Git submodule. This is a step up but not ideal either.

I’ll have a big blog post and screencast coming up about exactly this topic using Composer to manage WP core and keep it out of your repos. It’s a little advanced but after using it for a bit it’s much better than the alternative.

Despite the goal of having your dev/prod environments exactly the same, it’s never going to happen completely. SSL is one of those things.

Our Vagrant setup is completely customizable but that’s up to someone on their own. Yeah, Apache is still really popular but we can only provide a setup that we’re familiar with using.

Thanks. I’d be interested to know how people manage the different environments. I’m starting out on this different set up and I’d be interested to know how you get round potential issues.

Totally understand you will only be able to provide help with the set up you are familiar with, but I assume it wouldn’t be too hard to switch nginx for Apache?

Thanks, Scott! Good to know I’m not the only one who found this to be a challenge. Looking forward to your post about Composer.

I just instaled Vagrant. Big problems on Windows7. Not with program itself but when you download first box it takes time, for me 40min. And near the and it broke (three times). When I switch to Ubuntu it was better (even download was 4 time faster ???). But install instruction are wery poor. How hard is to tell people what to do before installation and how instalation process look like. They wanted to look simple, just install and UP, thats it. But in real life, with real people that isnt case. When I started instalation Vagrant tells you to remove Virtual-Box. Later it tells you to install it. This must be in instalation instructions. Its only few lines more of text. Did not help that I first downloaded 32 bit version and missed couple of librarys.
But when it start working its miracle to see virtual web server up with 5 lines of text and one script (example from site).