File-system layout for WordPress - using composer and git

We assume you are already familiar with composer. If not please read Getting Started with Composer for WordPress Projects first.

Before we really get going with composer, we need to make few changes to WordPress default setup to make it more composer/git friendly.

File System Layout

Following are example content for webroot. Usually htdocs,public_html orwww folder depending on your server config.

composer.json
composer.lock
index.php
wordpress/
wp-content/
uploads/
wp-config.php
.gitignore

Let’s explain each of above one-by-one.

.gitignore file

Some files and folders will be automatically created and showed above for illustration only. This also means we shall not put them under version control. So at bare minimum, please add following to .gitignore

vendor/
wordpress/
wp-content/

vendor directory will be created by composer at runtime. We won’t be using it for any purpose.

“wordpress” directory

We will giving WordPress core it’s own directory. WordPress supports this kind of setup since long time.

Please note that you don’t need to create this directory or download WordPress yourself. Composer will take care of this.

index.php in webroot

In order to support above, we will need to copy index.php from WordPress folder to root (htdocs) folder and edit it to include “wordpress” folder path. You can use example below as it is:

<?php
/**
 * Front to the WordPress application. This file doesn't do anything, but loads
 * wp-blog-header.php which does and tells WordPress to load the theme.
 *
 * @package WordPress
 */

/**
 * Tells WordPress to load the WordPress theme and output it.
 *
 * @var bool
 */
define('WP_USE_THEMES', true);

/** Loads the WordPress Environment and Template */
require( dirname( __FILE__ ) . '/wordpress/wp-blog-header.php' );

You can notice wordpress/ in last line.

“wp-content” directory

Next we need to move wp-content outside wordpress directory. WordPress supports this as well.

Again, you no need to create wp-content or download any themes/plugins. Composer will be doing this for you.

wp-config.php

For our non-default layout to work, we need to add some lines to our wp-config.php files.

You can add following at the top (after <?php tag)

define('WP_SITEURL', 'https://' . $_SERVER['SERVER_NAME'] . '/wordpress');
define('WP_HOME',    'https://' . $_SERVER['SERVER_NAME']);
define('WP_CONTENT_DIR', dirname(__FILE__) . '/wp-content');
define('WP_CONTENT_URL', 'https://' . $_SERVER['SERVER_NAME'] . '/wp-content');

First two lines takes care of wordpress directory and next two lines takes care of wp-content directory.

Moving wp-config.php outside webroot (optional)

As you may have noticed, wp-config.php is present in public webroot directory here.

Method of moving wp-config.php one-level up will not work here. This is because we are already one level up with respect to wordpress directory. But we can still move it a level up by doing some extra work:

With original wp-config.php

Move original wp-config.php one level up, outside webroot. Let’s call webroot htdocs here. It can be public_html, www or anything else. What you call your folder doesn’t matter as long as you remember it’s name.
Change line define('WP_CONTENT_DIR', dirname(__FILE__) . '/wp-content'); to include webroot folder as this line refers to absolute filesystem path. In our case, it will become define('WP_CONTENT_DIR', dirname(__FILE__) . '/htdocs/wp-content');
Now go to last line #require_once(ABSPATH . 'wp-settings.php'); and comment it out.

Create a new “fake” wp-config.php

After moving and modifying original wp-config.php, we need to create a fake/placeholder wp-config.php in webroot. Remember WordPress cannot lookup two level up for wp-config.php.

You can put following wp-config.php as it is:

<?php
/** path to real wp-config.php **/
require_once( dirname(__DIR__) . '/wp-config.php');

/** Sets up WordPress vars and included files. */
require_once(ABSPATH . 'wp-settings.php');

composer.lock file

As explained in previous chapter, composer.lock file will be generated automatically. So we no need to explore more about it.

composer.json file

At bare minimum composer.json file for WordPress will look like below:

{
    "require": {
        "johnpbloch/wordpress": "4.2.2"
    }
}

Composer’s official repo has a composer package for WordPress maintained by John P. Bloch.

You can copy above content in composer.json file on your filesystem or run composer init --require johnpbloch/wordpress:4.2.2 which will generate a composer.json file followed by an interactive wizard.

In either case, you will have a composer.json file.

Next, run composer install command, it will create awordpress directory and download WordPress version 4.2.2 in it. You can specify any other version and it will get dowloaded.

You will also see a vendor directory and composer.lock file generated. You no need to dig into them.

In next chapter, we will explore composer.json in more details.

Don’t forget to git commit/push changes you have made so far. From here onwards you will be only editing composer.json and running composer update command to update composer.lock file. Other files will remain mostly untouched.

Git and File-System Layout (non-default setup)