Skip to content
Black Friday

20% off for every Pro licenses

BLACKFRIDAYClaim the Offer
Contact us

Making Your Plugin Cloud-Aware

Most plugins work with offloaded media without any changes, because Media Cloud Sync filters the standard WordPress media functions. This guide covers the cases where you need to do a little more.

Getting media URLs

Use the core functions. They return cloud (or CDN) URLs for synced media and local URLs for everything else:

wp_get_attachment_url( $id );                       <em>// full file</em>
wp_get_attachment_image_src( $id, 'medium' );        <em>// sized image</em>
wp_get_attachment_image( $id, 'large' );             <em>// <img> with cloud src + srcset</em>
wp_get_attachment_image_srcset( $id, 'large' );

Avoid building URLs yourself from wp_upload_dir()['baseurl'] plus a stored path. Those URLs bypass the plugin and point at your server, where the file may no longer exist.

Rewriting URLs in your own content

The plugin hooks into these WordPress filters, so anything passed through them is rewritten automatically:

FilterDirection
the_content, the_excerpt, rss_enclosureLocal → cloud (on output)
content_edit_pre, excerpt_edit_preLocal → cloud (when loaded into the editor)
the_post (post object fields), content_paginationLocal → cloud
content_save_pre, excerpt_save_preCloud → local (on save, so the database keeps local URLs)

If your plugin stores HTML, JSON, or CSS with media URLs somewhere else (custom tables, options, post meta, builder data), choose based on what else the content needs:

Just the URL rewrite: use wpmcs_filter_post. Only media URLs change; nothing else is touched.

$html = get_option( 'my_plugin_banner_html' );
echo apply_filters( 'wpmcs_filter_post', $html );

Full WordPress content formatting: if the content should behave like post content anyway (paragraphs, shortcodes, embeds, responsive images), pass it through the_content. URLs are rewritten as part of that filter.

echo apply_filters( 'the_content', get_post_meta( get_the_ID(), 'intro_html', true ) );

the_content also runs wpautop, shortcodes, oEmbeds, and every other plugin’s content filters. Don’t use it for JSON, CSS, or raw attribute values; use wpmcs_filter_post there.

Excerpt-style text: the_excerpt works the same way for short summaries.

JSON-encoded content works as long as slashes aren’t escaped:

$json = wp_json_encode( $data, JSON_UNESCAPED_SLASHES );
$json = apply_filters( 'wpmcs_filter_post', $json );

If your site is reachable on several hostnames, register the extra ones with wpmcs_server_domains so their URLs are rewritten too.

Reading offloaded files

When Remove files from server is on, the local file is gone. get_attached_file() then returns something other than a local path. In order of preference:

1. Read through the stream path (default)

For synced media whose local file is missing, get_attached_file() returns a read-only stream path:

wpmcssw://my-media-bucket/wp-content/uploads/2026/10/photo.jpg

Standard PHP functions can read it:

$path = get_attached_file( $id );

$data = file_get_contents( $path );   <em>// works</em>
$size = getimagesize( $path );        <em>// works</em>
$fh   = fopen( $path, 'rb' );         <em>// works (read modes only)</em>

It’s read-only. Writing, renaming, deleting, mkdir, and directory listing all fail. Code that checks file_exists() before reading still works.

2. Copy the file back to the server

If your code needs a real local file (for example to pass to a command-line tool), ask for it to be downloaded first:

add_filter( 'wpmcs_get_attached_file_copy_back_to_server', function ( $copy, $file, $id ) {
    return doing_action( 'my_plugin_process_image' ) ? true : $copy;
}, 10, 3 );

For REST-driven processing, list your route instead. The plugin downloads files during the request and removes them again afterwards when Remove files from server is on:

$route = '/my-plugin/v\d+/optimize/';
add_filter( 'wpmcs_rest_api_enable_get_attached_file_copy_back_to_server', fn( $r ) => array_merge( $r, [ $route ] ) );
add_filter( 'wpmcs_rest_api_enable_get_attached_file_remove_from_server', fn( $r ) => array_merge( $r, [ $route ] ) );

3. Use the URL

For read-only use, wp_get_attachment_url() plus wp_remote_get() is the simplest and works everywhere.

Changing a file and pushing it to the cloud

If your plugin modifies an attachment’s files (crop, optimize, watermark, convert), re-sync it afterwards:

<em>// 1. Make sure the file is local (see "Copy the file back to the server").</em>
<em>// 2. Modify it, update metadata as usual.</em>
wp_update_attachment_metadata( $id, $meta );

<em>// 3. Upload the new version (and its sizes) to the cloud.</em>
add_filter( 'wpmcs_do_reupload_media', '__return_true' );
do_action( 'wpmcs_do_update_attachment_metadata', false, $id );
remove_filter( 'wpmcs_do_reupload_media', '__return_true' );

Without wpmcs_do_reupload_media, files whose name and size haven’t changed may be treated as already uploaded.

Tip: When object versioning is off, browsers and CDNs may keep serving the cached old file. Turn on Object versioning, or append a version query string through wpmcs_wp_get_attachment_url.

Reacting to sync events

<em>// Each time an attachment finishes uploading.</em>
add_action( 'wpmcs_post_update_item', function ( $id, $data, $source_type ) {
    if ( 'media_library' === $source_type ) {
        do_action( 'my_plugin_media_offloaded', $id );
    }
}, 10, 3 );

<em>// When a bulk "Sync Media to Cloud" run completes.</em>
add_action( 'wpmcs_sync_to_cloud_completed', 'my_plugin_after_bulk_sync' );

<em>// When an item's files were uploaded again under the same names, for example to clear your own cache.</em>
add_action( 'wpmcs_files_replaced', function ( $source_id, $source_type ) {
    my_plugin_clear_cache( $source_id );
}, 10, 2 );

Checking whether an item is offloaded

See Helper API.

Checklist

  • [ ] Use wp_get_attachment_*() functions for URLs, not paths built from wp_upload_dir().
  • [ ] Pass custom-stored HTML/JSON through wpmcs_filter_post.
  • [ ] Read files through get_attached_file(). Request a copy-back if you need a writable local file.
  • [ ] After changing files, trigger wpmcs_do_update_attachment_metadata.