The first point release of MasterPress, version 1.0.1, includes 2 important changes which may have ramifications for sites already using version 1.0:
- The location of the “mp” folder, where MasterPress stores all of its content (uploads, icons, cached images, and other files) will change from being located at wp-content/mp to wp-content/uploads/mp instead.
- In a WordPress multisite environment, MasterPress will no longer share post type, taxonomy, field set, field, and role definitions between sites by default, but will instead create separate definitions for each site in the network.
This post deals with the first of these issues. For more info on the multisite change, please refer to the separate post “Multisite Sharing in 1.0.1“.
Note: the changes outlined in this post should have little consequence for new installations of MasterPress 1.0.1.
The legacy content folder location in 1.0
In version 1.0 of MasterPress, the “mp” content folder was created at the following locations:
- Single Site: wp-content/mp
- Multisite: For each site with a given “blog_id” number, MasterPress would store content in blogs.dir/{blog_id}/mp. Note that MasterPress 1.0 would even do this for fresh installs of 3.5, which wasn’t quite right (see “Supporting Multisite in WordPress 3.5” below).
The new content folder location in 1.0.1
As of 1.0.1, MasterPress now stores its content folder in the following locations by default (where {blog_id} represents the ID of each site in a multisite installation):
- Single Site: wp-content/uploads/mp
- Multi-site (WordPress 3.5+): wp-content/uploads/sites/{blog_id}/mp
- Multi-site (Current WordPress < 3.5 or first-installed on on < 3.5): wp-content/blogs.dir/{blog_id}/mp
MasterPress will also now observe any custom upload directory configuration, and store its content there instead (noting that most users don’t generally configure a custom directory).
Also note that the location of the content folder has not changed for multisite installations running a WordPress version less than 3.5, or where the site was first setup with a version less than 3.5 – this is also referred to as an “ms-files” setup.
The “mp/uploads” sub-folder is now “mp/files”.
Now that the mp content folder resides within the uploads folder, we have also changed the name of the uploads sub-folder inside the mp folder to files, to avoid duplication of the word “uploads”. This change is documented in the migration steps inside MasterPress itself (see below).
The Migration process for existing installations
MasterPress 1.0.1 is able to detect installations that are using the legacy directories, and these sites should continue to work. If you wish to migrate an existing installation to these new directories, you first need to define the following configuration variable in the wp-config.php file:
Once this is defined, if you then visit the Masterplan menu item in the dashboard you’ll be greeted with the message similar to the screenshot below, with instructions for migrating to the new location.
Update: Note that the original instructions when this post was first published suggested that this migration would be mandatory, but I don’t feel there is any particular need to force existing installations to use the new directories.
Important: This process also includes a database migration step to move any custom field values across to new URL locations, so it’s a very good idea to backup your database before running the migration.
Follow these instructions, and you should be good to go with the new setup. And please don’t hesitate to raise a support issue if anything goes wrong.
Why has the location changed?
Moving the MasterPress content folder is certainly a disruptive change, and it was not a decision we made lightly. There are a number of reasons why we made this change, but its useful to first discuss why it was stored directly inside wp-content in the first place.
In a nutshell, when initially planning out MasterPress and deciding where the content folder should be placed, I had a philosophical issue with storing the folder inside wp-content/uploads, as I didn’t consider many of the files inside the MasterPress content folder to be strictly uploads.
There were a few problems with this semantic ideal though:
1. File permissions problems are painful
Setting up the correct permissions on the wp-content folder directly is never trivial, especially for novice users who haven’t had to deal with file permissions before. This is the reason for the slightly convoluted initial setup process in version 1.0.
Ideally, we only want users to have to deal with configuring the correct upload directory permissions once, which they need to do at some stage to get any type of upload working (or indeed may not need to do at all if their hosting platform takes care of this standard requirement).
By storing the MasterPress content folder inside wp-content/uploads, we can take advantage of the fact that the permissions are likely already correct in most installations, and we can create the MasterPress folders without any issue (just like WordPress can create new year-based upload folders as time goes by).
I also suspect this is why popular plugins like BackupBuddy choose to use “uploads” too – while backups aren’t strictly uploads either, it just makes everything easier to setup and maintain correctly.
2. Supporting Multisite in WordPress 3.5
As of WordPress 3.5, the location of files for additional sites in a multisite network has changed to be within “uploads” anyway, specifically inside wp-content/uploads/sites/{blog_id}. So it seemed there was little point in trying to store these files outside of uploads, as this would require even more separate folders for other sites in a network.
Note that we weren’t actually aware of this change to WordPress 3.5, period, and so MasterPress 1.0 didn’t correctly support this new setup – instead being coded to use the legacy blogs.dir structure every time. This version 1.0.1 change also addresses this issue to correctly support the new 3.5 upload directory structure.
3. Supporting custom upload directories
By requiring the content folder inside wp-content, MasterPress also didn’t support custom upload directories at all. This change also allows us to address this issue, and MasterPress now stores content inside the configured uploads directory, noting that this is usually wp-content/uploads as most users don’t change this setting.
A disruptive change for the better
So, while these changes are a little disruptive, we felt that it was best to address this early on while the MasterPress user-base is still relatively small. We didn’t like making this change ourselves, since it’s a lot of work to document and support the migration. But the benefits outweigh the negatives, and being able to simplify the MasterPress initial setup process for new installations in particular is a massive win.
Again, please don’t hesitate to raise a support issue if you have trouble with migrating a site from version 1.0.