How to Move Media to a New Bucket Path

Release 2.4 of WP Offload Media introduced the ability to move all of your existing offloaded media to a new bucket path, without the need to remove from bucket and re-offload.

There are a number of reasons why one might want to do this:

• Turning on the recommended Object Versioning or Year/Month settings
• Changing the Path to better identify the site’s media in a shared bucket
• Turning on or off, or changing the path used for Private Media

Changing Storage Path Settings

When you update the Path, Year/Month or Object Versioning settings, WP Offload Media will prompt you to move all of your existing offloaded media to the new path format.

If you choose “No”, nothing happens and the plugin continues to work the same as it did before: existing offloaded media stays where it is, and new media is uploaded to the bucket using the newly chosen storage path settings.

If you choose “Yes”, WP Offload Media will kick off a background process to move all of your offloaded media files to paths that match the new storage path settings. This only affects media which has already been offloaded. It does not have any effect on media which has yet to be uploaded, that is in a different bucket than the currently configured one, or that has been offloaded to a different storage provider. A sidebar tool will appear to show the progress and a notice will appear in wp-admin once the operation is complete.

Each offloaded Media Library item is checked to see whether its bucket path needs updating to match the current settings. If a Media Library item’s path already matches the current settings format then it is skipped and not moved.

If a private image’s storage path is updated, any alternate sizes of the image that are public will also have their path updated for consistency.

Because the operation happens completely on the storage provider, the whole process is very quick and usually finishes within a few minutes, even with thousands of files.

If you chose “No” to the move storage path prompt and later wish to move the objects, you can use a define to show the Move files to new storage path tool in the settings page’s sidebar.

You may not get the Storage Path Updated prompt for moving media in the bucket if turning off the Year/Month or Object Versioning settings.

This is a safety feature as turning off either of those settings could mean that previously unique bucket paths for some Media Library items are no longer unique. Moving the objects could lead to data loss as one object overwrites the path of another.

If you’re absolutely sure all object paths will still be unique after turning off either the Year/Month or Object Versioning settings, then you may force WP Offload Media to show the Move Public Objects tool with its wp-config.php constant.

Changing Private Path Settings

If your site is using Amazon CloudFront as the delivery provider for media in Amazon S3, it is possible to serve private media via signed CloudFront URLs.

As part of the setup for signed CloudFront URLs a Private Path is specified that acts as a prefix to the public path normally used for offloaded Media Library items.

When Private Media is enabled or disabled, or the Private Path changed, WP Offload Media will prompt to move private media to the newly configured Private Path.

If you choose “No”, nothing happens and the plugin continues to work the same as it did before: existing offloaded private media stays where it is, and newly offloaded private media is uploaded to the configured private prefix or uses the public storage path if Private Media has been turned off.

If you choose “Yes”, WP Offload Media will kick off a background process to move all of your private media file offloads to paths that match the new private path settings. This only affects private media which has already been offloaded. It does not have any effect on media which is in a different bucket than the currently configured one, or that has been offloaded to a different storage provider. A sidebar tool will appear to show the progress and a notice will appear in wp-admin once the operation is complete.

Each offloaded Media Library item is checked to see whether it has private objects whose private bucket path needs updating to match the current settings. If a Media Library item’s path already matches the current private path settings format then it is skipped and not moved.

It is important to note that if Private Media is turned off then private objects will be moved back to their standard public storage path. WP Offload Media will then serve private media via signed S3 URLs rather than signed CloudFront URLs.

Similarly, if “No” is chosen when prompted to move private media due to the private path changing, any offloaded private media that now has a different private prefix will be served via signed S3 URLs instead of signed CloudFront URLs. Only private Media Library items that are known to have a private path prefix that matches the current setting will have signed CloudFront URLs.

Because the operation happens completely on the storage provider, the whole process is very quick and usually finishes within a few minutes, even with thousands of files.

If you chose “No” to the move private path prompt and later wish to move the objects, you can use a define to show the Move files to new private path tool in the settings page’s sidebar.

Changing Both Storage & Private Path Settings

If you change both the storage path and private path before saving changes, you will see prompts for the changed storage and private path one after the other.

You can choose “Yes” or “No” to either prompt as you see fit.

If you choose “No” to both prompts, no objects will be moved.

If you choose “Yes” to one prompt and “No” to the other, then only the move operation associated with the “Yes” will be performed as you might expect.

If you choose “Yes” to both prompts then both public and private paths for all offloaded media Library items that need changing will be processed in one go. This is a more efficient way of moving both public and private objects than changing Storage Path settings and then changing Private Path settings, as WP Offload Media only then needs to process the Media Library once, taking care to move objects to their new paths in one combined Move files to new path prefix process.

Using Constants

If you use settings constants to define your chosen Path and Private Media settings in your wp-config.php file, then the above prompts will not be available because the ability to change those settings through the UI is not possible.

Show Move Files to New Storage Path Tool

You can still use the Move files to new storage path tool by enabling it in the sidebar with the following define in your wp-config.php.

define( 'AS3CF_SHOW_MOVE_PUBLIC_OBJECTS_TOOL', true );

Clicking “Begin Move” will start the move process, using your currently defined storage path settings as the format to move the public objects to.

Once the process has been started you may remove the AS3CF_SHOW_MOVE_PUBLIC_OBJECTS_TOOL define, the tool will continue to work in the background and show its progress in the sidebar, removing itself from the sidebar once complete.

Show Move Files to New Private Path Tool

You can still use the Move files to new private path tool by enabling it in the sidebar with the following define in your wp-config.php.

define( 'AS3CF_SHOW_MOVE_PRIVATE_OBJECTS_TOOL', true );

Clicking “Begin Move” will start the move process, using your currently defined private path settings as the format to move the private objects to.

Once the process has been started you may remove the AS3CF_SHOW_MOVE_PRIVATE_OBJECTS_TOOL define, the tool will continue to work in the background and show its progress in the sidebar, removing itself from the sidebar once complete.

Show Move Files to New Path Prefix Tool

You can still use the Move files to new path prefix tool by enabling it in the sidebar with the following define in your wp-config.php.

define( 'AS3CF_SHOW_MOVE_OBJECTS_TOOL', true );

Clicking “Begin Move” will start the move process, using your currently defined storage and private path settings as the format to move both the public and private objects to as appropriate.

Once the process has been started you may remove the AS3CF_SHOW_MOVE_OBJECTS_TOOL define, the tool will continue to work in the background and show its progress in the sidebar, removing itself from the sidebar once complete.