How to properly change and reference various WordPress directories

Using WordPress, it’s a poor assumption to assume the wp-content, plugins, and uploads folders are always in the same place, or even always called by those names.

The configuration you see above is a sample WordPress root directory. This isn’t uncommon. Many people who manage their installs with version control such as Git probably recognize this format.

As you can see above, WordPress core has its own folder, wp, so that core is not at the root level. This allows us to include WordPress as a submodule of our project, and makes for a cleaner experience.

You’ll also notice that wp-content is actually called content.

Now you can see why it’s not a good idea to hard code the uploads, plugins, or wp-content directories into your plugins.

This point was made by Pippin Williamson on Twitter the other day, and he and Brad Touesnard discussed it on Apply Filters yesterday — an excellent podcast by the way.

How to change default directories

You can see how to edit wp-config to define the wp-content directory and URL using constants in wp-config.php.

define('WP_CONTENT_DIR', __DIR__ . '/content' );
define('WP_CONTENT_URL', 'http://mysiteurl.dev/content');

You can similarly alter your default plugins directory:

define( 'WP_PLUGIN_DIR', dirname(__FILE__) . '/content/plugins' );
define( 'WP_PLUGIN_URL', 'http://mysiteurl.dev/content/plugins' );

And again for uploads:

define( 'UPLOADS', '/content/uploads' );

You can learn more about various things you can define and utilize with this excellent Codex resource.

How to reference default directories, the right way

Now, let’s show a couple examples for referencing these directories the right way.

First, let’s see how WordPress core defines one of the functions that references these paths. I’ll use the content_url function as an example:

[gist id=”8fdd5f00d6372e5d48e1″]

You can see above that WordPress uses the defined constant, but the function offers a parameter of adding an additional path, then cleans that up to make sure it won’t break, and finally a filter for other plugin developers to utilize if need be.

The plugins_url and wp_upload_dir functions operate similarly, though the core code is more complex.

The most common of these functions to use in the real world is probably plugins_url. It’s a really bad idea to directly reference /wp-content/plugins, for reasons we’ve stated already, so here’s how you could properly use plugins_url to load scripts in the WordPress admin. This is one snippet from another of Pippin’s tutorials, which you should of course read:

[gist id=”6509862fb7d283776a66″]

To see more functions for properly referencing various directories in WordPress, check out the related functions to content_url on the codex.

You can also utilize a constantly directly in your code. Here’s a sample from Pippin’s Easy Digital Downloads plugin where I plucked a section of a series of checks he’s doing for file requests and processing:

[gist id=”3b91d3cbd3c580218f39″]

In this case, no filters would be applied, and he knows exactly what to expect with the constant.

Go out and properly reference directories

You should now have a decent grasp on the right way to change and then reference various directories of WordPress.

As Pippin and Brad note in their podcast, you can get away without doing it the right way for most sites, but inevitably you are going to break something, especially with distributed code. So you might as well start using the best practice now.