Tame the WordPress Media Library with a custom uploads folder structure.
WordPress does not offer enough personalisation for organising media uploads. With this plugin, users are not beholden to the default:
/wp-content/uploads/2023/03/image.jpeg
Instead, media folders can mimic a site's content structure, with any of these elements:
/wp-content/uploads/post_type/taxonomy/term_slug/YYYY/MM/slug-of-the-post/image.jpeg
For example:
/wp-content/uploads/post/client/acme-inc/image.jpeg/wp-content/uploads/category/technology/macbook.png/wp-content/uploads/review/cuisine/japanese/sushi-house.jpeg/wp-content/uploads/2023/03/my-awesome-post/image.jpeg
WordPress' default media organisation does not scale. My site with 10,794 posts had 9,488 media items. Accounting for the different sizes WordPress generates, this was 22,021 individual files, totalling 2.25Gb, all organised in YYYY/MM folders under /wp-content/uploads.
Chronology was not the natural way organise such a large and disparate set of images.
The posts to which many of these images belong fall into a number of distinct groups. I had already grouped content using taxonomies. I wanted to batch these images similarly, to make the image folder structure mirror the content structure, and to make potential future migration, perhaps even away from WordPress, smoother.
I once used a combination of existing library management plugins and manual effort to reorganise images. But it was a huge and one-time task that I never wanted to repeat. Instead, I want WordPress to comply with my own media organisation preferences automatically, as I go, and to batch-reorganise images more efficiently.
This required developing a plugin to force WordPress to organise media as I want.
WP Tidy Media offers the following reorganisation features. Each can be enabled individually:
Post-attached images will be moved to your specified custom folder structure, which can mirror your content structure. This includes Featured Image and other attachments.
Media of all local image URLs found in post body content (whether attached or not) will be moved to your custom folder structure. <img src in post body will be updated accordingly.
By default, WordPress inserts images into post content using absolute URLs (eg. <img src="http://www.yourblog.com/wp-content/uploads/2023/03/image.jpeg">). This can make site migration - and even local development of a deployed website - complicated, because images will appear broken. By contrast, relative URLs will always point to the image, wherever you host the site.
Any of your own images called via absolute URLs will be replaced by a corresponding relative URL (eg. <img src="/wp-content/uploads/2023/03/image.jpeg">). This does not move images.
All off-site images found in post body content will be pulled to your site. Applies to all <img src= URLs except your own site and specified "additional home domains". Organisation will be as per the other settings.
When a post is deleted, any attached media will also be deleted. Only deletes if attachment is unused elsewhere.
WP Tidy Media can be used in two ways:
- Run on every post save (optional).
- Run in bulk from the Posts list, via a button.
You can run on every post save to ensure the library is kept organised in the future.
You can run in batch to reorganise your Media Library retrospectively. If you change your mind, you can change your custom file path after a batch run, and then run again - attachments will be moved again.
In either event, the functions you choose in Options will be executed.
Access "Tidy Media" settings from beneath the core "Media" menu.
| Setting | Option |
|---|---|
| Tidy post attachments | Enable/disable |
| Tidy body image URLs | Enable/disable |
| Convert body image URLs from absolute to relative | Enable/disable |
| Localise remote body images | Enable/disable |
| Delete attachments with posts | Enable/disable |
| Log operations | Enable/disable |
| Setting | Option |
|---|---|
| Organise by post type? | Enable/disable |
| Organise by taxonomy | Choose taxonomy, or None. |
| Use date folders | (Set in Media Settings) |
| Organise by post slug? | Enable/disable (eg. my-awesome-post) |
| Setting | Option |
|---|---|
| Remove home URL | Shows how the hostname will be removed to construct a relative URL. |
| Additional home domains | Add any other hostnames/domains to strip out (for users who may have <img src URLs from legacy sites). |
The plugin will act on all three kinds of image files an attachment can represent:
- Main web-ready image file.
- Sizes files, for the range of thumbnail and other output sizes.
- Original image.
Since 5.3, when an uploaded image is over 2560px in height or width, WordPress downsizes the primary file it will serve and also retains the original.
Moving the files alone to your custom folder path is insufficient. This plugin also makes changes to attachments' corresponding database records:
wp_postmeta:
- _wp_attachment_metadata: Updates the serialised array to reflect new file location.
- _wp_attached_file: Updates the relative image path.
wp_posts:
- post_parent: Where an image is not already attached to another post and is designated to be attached to the current post, this attachment occurs by setting the post's ID as the attachment's post_parent.
- post_date: Where a change is being made to an attachment (ie. a reorganisation, or a new image is added to the Media Library), it will take on the date of the post itself. This is to avoid flooding the Media Library with new items.
- guid: Where an attachment is being moved, its guid (unique indicator) field will also be updated. Only the sub-directory portion is changed, the domain is not changed. Note: WordPress developers advise against changing guid for posts. This plugin runs on "attachment" post objects, for which guid is somewhat inconsequential, and is designed primarily for site overhauls which aim to run correct guids.
Features are run logically in this order:
- Localise remote images.
- Convert body images to relative URLs.
- Relocate other images found in posts.
- Relocate post attachments.
Attachment deletion with post deletion occurs at time of post deletion, if enabled.
- Upload the
wp-tidy-mediafolder to the/wp-content/plugins/directory. - Activate the plugin through the 'Plugins' menu in WordPress.
- Access "Tidy Media" settings from beneath the core "Media" menu.
WP Tidy Media does not store settings in wp_options or any core WordPress database table.
For neatness, it uses its own distinct table, wp_tidy_media_organizer.
This table is created on plugin activation, and a small number of settings is set.
The plugin tidies up after itself. Upon deletion, the table wp_tidy_media_organizer is deleted. This removes all traces of the plugin.
Removal will not affect changes already made by this plugin - any attachments already moved will remain in their new locations.
Deletion of the plugin will not revert attachments to their prior state.
Running these operations may pose risks to your Media Library.
Make a back-up of both files and database before you run this plugin.
The author cannot be held liable for any data loss.
- Initial release
This plugin is licensed under the MIT License - see the LICENSE file for details.