A COMPLETE GUIDE TO WORDPRESS IN ITS OWN DIRECTORY ON PANTHEON

Neatly Organizing Your WordPress on Pantheon Hosting

In the digital realm, maintaining order and organization can be as satisfying as tidying up a physical space. For those like me who appreciate neatness, keeping WordPress core files in a dedicated subdirectory is a preferred practice. However, when it comes to Pantheon managed WordPress hosting, achieving this can be a bit challenging. In this guide, we’ll explore the concept of “WordPress in its Own Directory” on Pantheon and provide you with a solution to implement it seamlessly.

Understanding “WordPress in its Own Directory”

If you’re unfamiliar with the concept, “WordPress in its own directory” involves placing all core WordPress files and directories (such as wp-includes and wp-admin) inside a subdirectory within your website’s document root, rather than having them directly in the document root itself.

This approach offers several benefits:

1. Enhanced Organization

2. Improved Security

3. Compatibility with Composer

Let’s delve into the steps to achieve this on Pantheon.

Step 1: Setting the Stage

Before we proceed, let’s establish some assumptions and prerequisites:

Assumption 1: web_docroot Configuration

I assume you have configured your pantheon.yml file with web_docroot: true, which sets the document root to /code/web instead of just /code. This is for better organization and security.

Assumption 2: Subdirectory Naming

We will use the subdirectory named wp/ to house WordPress core files. You can choose a different name if you prefer, but for consistency, we’ll stick with wp/ in this guide.

Assumption 3: Website Name

For convenience, we’ll refer to the website as “mysite.”

Assumption 4: Upstream

I’m using an empty WordPress upstream for all Pantheon sites. If you use Pantheon’s default WordPress upstream, you may need to adjust these instructions accordingly.

Assumption 5: Technical Proficiency

This guide assumes a certain level of command-line Linux proficiency, including git cloning and symbolic linking.

Step 2: Moving WordPress to Its Subdirectory

Let’s begin the process of relocating WordPress to its own directory:

1. Clone your Pantheon site (e.g., mysite) onto your local machine using git clone.
2. Create a directory within the web/ directory for your WordPress files. We’ll call it wp/.
3. Move all WordPress core files and directories (e.g., wp-admin, wp-includes, etc.) into the newly created wp/ directory. Ensure you include files like index.php, license.php, and readme.html. Notably, exclude wp-config.php and wp-content/ for now.
4. Copy (do not move) the index.php file from the web/ directory, and modify the last line to read:
   php

   require( dirname( __FILE__ ) . '/wp/wp-blog-header.php' );

5. Locate the wp-config.php file. Since Pantheon provides a customized wp-config.php, keep it in the web/ directory (outside of wp/).
6. In your wp-config.php, find the line starting with define('WP_SITEURL', and modify it to read:
   php

   define('WP_SITEURL', $scheme . '://' . $_SERVER['HTTP_HOST'] . '/wp');

7. After the define('WP_SITEURL'… line, add these two lines:
   php

   define( 'WP_CONTENT_DIR', dirname( __FILE__ ) . '/wp-content' );
define( 'WP_CONTENT_URL', WP_HOME . '/wp-content' );


Now, you can test your website on your development environment. If it works correctly, proceed to test it on the staging environment and finally on the live site.

Step 3: Configuring wp-cli.yml

During my transition to Pantheon, I encountered issues with cache clearing when using “WordPress in its own directory.” To resolve this, I discovered a crucial configuration file: wp-cli.yml. Follow these steps:

1. Run the cache-clearing process using Pantheon’s command-line tool, terminus:
   bash

   terminus env:clear-cache mysite.live

2. If you receive an error indicating, “This does not seem to be a WordPress install,” it’s likely a wp-cli error.
3. To address this, create a file named wp-cli.yml in the root (code/) directory of your Pantheon project with the following content:
   yaml

   path: web/wp


This file specifies the path to your WordPress installation within the wp/ subdirectory.

Step 4: Resolving Plugin and Theme Issues

You may encounter issues with wp-cli commands related to plugins and themes. To address this, create a symlink to your wp-content/ directory within the wp/ directory:

Commit this change to your Git repository and push it to your Pantheon repository. Then, deploy these changes through the Pantheon dev/test/live workflow.

With these adjustments, running wp-cli commands like terminus wp mysite.live -- plugin list should now provide a complete list of your plugins and themes.

Conclusion

While the process of organizing your Pantheon installation with “WordPress in its Own Directory” may not be extensively documented, it is a valuable technique for those who appreciate digital neatness. I hope this guide has helped you achieve a cleaner, more organized WordPress setup on Pantheon. It’s worth noting that Pantheon has shown interest in improving documentation for this approach, so stay tuned for potential updates.

If you’re a perfectionist when it comes to digital order, implementing these steps can significantly enhance your Pantheon hosting experience, ensuring everything is in its rightful place and functioning correctly.