---
title: "Making Your Plugin Cloud-Aware"
url: "https://dudlewebs.com/guideline/media-cloud-sync/developers/making-your-plugin-cloud-aware/"
markdown_url: "https://dudlewebs.com/guideline/media-cloud-sync/developers/making-your-plugin-cloud-aware.md"
type: "Docs"
language: "en-US"
date_published: "2026-11-08T11:24:43+00:00"
date_modified: "2026-11-09T17:33:45+00:00"
---

# 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:

```html
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:

| Filter | Direction |
| --- | --- |
| `the_content`, `the_excerpt`, `rss_enclosure` | Local → cloud (on output) |
| `content_edit_pre`, `excerpt_edit_pre` | Local → cloud (when loaded into the editor) |
| `the_post` (post object fields), `content_pagination` | Local → cloud |
| `content_save_pre`, `excerpt_save_pre` | Cloud → 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.

```php
$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.

```php
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:

```php
$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`](https://dudlewebs.com/guideline/media-cloud-sync/developers/hooks-reference/#wpmcs_server_domains--wpmcs_remote_domains-filters) 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:

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

Standard PHP functions can read it:

```xml
$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:

```php
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:

```php
$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:

```xml
<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`](https://dudlewebs.com/guideline/media-cloud-sync/developers/hooks-reference/#wpmcs_wp_get_attachment_url-filter).

## Reacting to sync events

```xml
<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](https://dudlewebs.com/guideline/media-cloud-sync/developers/helper-api-and-data-model/#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`.

[← Previous Constants and Configuration](https://dudlewebs.com/guideline/media-cloud-sync/developers/constants-and-configuration/) [Next → Helper API and Data Model](https://dudlewebs.com/guideline/media-cloud-sync/developers/helper-api-and-data-model/)

Still need help?

[Chat with us Quick questions, answered live](https://dudlewebs.com/contact/) [Contact us Sales, partnerships or anything else](https://dudlewebs.com/contact/) [Create a ticket Technical issues with your site](https://dudlewebs.com/submit-ticket/)
