Constants and Configuration
All hooks are prefixed wpmcs_. Unless noted, $source_type is 'media_library' for Media Library attachments, and $item is a synced-item row (see Data model).
Contents
- Bucket paths and object keys
- URLs and delivery
- Content URL rewriting
- Uploads and image sizes
- Local file access
- Server and cloud cleanup
- Item lifecycle
- Background jobs
- Settings
- Access control
- Miscellaneous
- Admin UI schema
1. Bucket paths and object keys
wpmcs_object_key (filter)
Final object key (path inside the bucket) for an uploaded file.
apply_filters( 'wpmcs_object_key', string $object_key, string $relative_source_path, string $prefix );
| Parameter | Description |
|---|---|
$object_key | Key built from the prefix, Year/Month, versioning, and file name, such as wp-content/uploads/2026/10/photo.jpg. |
$relative_source_path | File path relative to the uploads directory, such as 2026/10/photo.jpg. |
$prefix | Versioning prefix (empty when object versioning is off). |
<em>// Store PDFs under a separate "documents/" folder.</em>
add_filter( 'wpmcs_object_key', function ( $key, $relative_path ) {
if ( str_ends_with( strtolower( $relative_path ), '.pdf' ) ) {
return 'documents/' . basename( $key );
}
return $key;
}, 10, 2 );
Change keys before syncing. Existing objects aren’t moved when the key logic changes.
wpmcs_keep_original_folder_structure (filter)
Return true to keep each file’s original sub-folder from the uploads directory instead of applying the Year/Month setting.
apply_filters( 'wpmcs_keep_original_folder_structure', bool $keep = false );
wpmcs_object_version_prefix (filter)
Folder added to keys when Object versioning is on. The default is a timestamp: ddHHMMSS/ with Year/Month on, or YmdHis/ with it off.
apply_filters( 'wpmcs_object_version_prefix', string $prefix );
add_filter( 'wpmcs_object_version_prefix', fn() => 'v' . time() . '/' );
wpmcs_get_relative_file_path_from_upload_directory (filter)
Path of a file relative to the uploads directory, used when resolving which file a URL or path refers to.
apply_filters( 'wpmcs_get_relative_file_path_from_upload_directory', string $relative_path, string $type );
wpmcs_private_object_key_root (filter)
Root folder used for objects stored as private. When nothing is hooked, private keys aren’t generated.
apply_filters( 'wpmcs_private_object_key_root', string $root = '', string $relative_source_path, string $prefix );
2. URLs and delivery
wpmcs_wp_get_attachment_url (filter)
Cloud URL returned for an attachment by wp_get_attachment_url().
apply_filters( 'wpmcs_wp_get_attachment_url', string $new_url, string $original_url, int $attachment_id );
<em>// Add a query-string version to cloud URLs for one post type's attachments.</em>
add_filter( 'wpmcs_wp_get_attachment_url', function ( $url, $original, $id ) {
return get_post_type( wp_get_post_parent_id( $id ) ) === 'product'
? add_query_arg( 'v', get_post_modified_time( 'U', true, $id ), $url )
: $url;
}, 10, 3 );
wpmcs_wp_get_attachment_image_attributes (filter)
Image tag attributes from wp_get_attachment_image_attributes, after src is rewritten to the cloud URL for the requested size. (srcset is rewritten separately through wp_calculate_image_srcset.)
apply_filters( 'wpmcs_wp_get_attachment_image_attributes', array $attr, WP_Post $attachment, string|array $size, array $item );
wpmcs_cdn_url (filter)
Final URL when Use Custom Domain Name (CNAME) is on.
apply_filters( 'wpmcs_cdn_url', string $new_url, string $provider_url, string $cdn_base_url );
<em>// Serve from a different CDN hostname in a staging environment.</em>
add_filter( 'wpmcs_cdn_url', function ( $url ) {
return wp_get_environment_type() === 'staging'
? str_replace( 'https://media.example.com/', 'https://staging-media.example.com/', $url )
: $url;
} );
Provider URL filters (filters)
Raw provider URL for an object, before any custom domain is applied.
apply_filters( 'wpmcs_generate_s3_file_url', string $url, string $domain, string $key ); <em>// Amazon S3</em>
apply_filters( 'wpmcs_generate_google_file_url', string $url, string $domain, string $key, string $bucket ); <em>// Google Cloud Storage</em>
apply_filters( 'wpmcs_generate_do_file_url', string $url, string $domain, string $bucket, string $key ); <em>// DigitalOcean Spaces, Cloudflare R2, S3-compatible</em>
wpmcs_should_serve_from_cloud (filter)
Whether a synced item is served from the cloud. Return false to serve that item from your server (the file must still exist locally).
apply_filters( 'wpmcs_should_serve_from_cloud', bool $serve = true, int $attachment_id, string $source_type );
wpmcs_is_available_from_provider (filter)
Whether a synced item counts as available from the provider for URL rewriting.
apply_filters( 'wpmcs_is_available_from_provider', bool $available = true, int $attachment_id, string $source_type );
wpmcs_generate_private_url (filter)
URL used for an item stored as private, before it’s cached for the configured lifetime.
apply_filters( 'wpmcs_generate_private_url', string $url, string $key );
3. Content URL rewriting
The plugin rewrites local media URLs to cloud URLs in post content, excerpts, and supported fields, and turns them back into local URLs when content is saved.
wpmcs_filter_post (filter)
Runs the plugin’s URL rewriting on any string. Use it for content stored outside post_content, such as page-builder data, custom tables, or JSON.
Content passed through the_content, the_excerpt, or rss_enclosure is rewritten automatically, so there’s no need to call this as well. See Rewriting URLs in your own content for when to use which.
$html = apply_filters( 'wpmcs_filter_post', string $content );
<em>// Rewrite media URLs in a custom field before output.</em>
echo apply_filters( 'wpmcs_filter_post', get_post_meta( get_the_ID(), 'gallery_html', true ) );
wpmcs_before_url_replace / wpmcs_after_url_replace (filters)
Content just before and just after a batch of URL replacements.
apply_filters( 'wpmcs_before_url_replace', string $content, array $find, array $replace );
apply_filters( 'wpmcs_after_url_replace', string $content, array $find, array $replace );
wpmcs_post_process_content (filter)
Content after all rewriting is finished.
apply_filters( 'wpmcs_post_process_content', string $content );
wpmcs_server_domains / wpmcs_remote_domains (filters)
Domains treated as “your site” (local URLs to rewrite) and as “the cloud” (URLs to turn back when saving). Add domains if your site is reachable under more than one hostname.
apply_filters( 'wpmcs_server_domains', array $domains );
apply_filters( 'wpmcs_remote_domains', array $domains );
add_filter( 'wpmcs_server_domains', function ( $domains ) {
$domains[] = 'old-domain.example.com';
return $domains;
} );
wpmcs_get_original_siteurl (filter)
Original site URL used to fix sub-site URLs on multisite. Defaults to network_site_url().
apply_filters( 'wpmcs_get_original_siteurl', string $url );
wpmcs_enable_backward_url_replacement (filter)
Switches URL matching into “backward” mode, where cloud URLs are converted back to local URLs. The plugin turns this on while saving post content. Enable it only while you’re converting stored content back to local URLs yourself.
apply_filters( 'wpmcs_enable_backward_url_replacement', bool $enabled = false );
wpmcs_push_to_url_pairs (filter)
Whether a matched item’s URL is added to the list of URL pairs to replace in content.
apply_filters( 'wpmcs_push_to_url_pairs', bool $push = true, int $source_id, string $source_type );
wpmcs_remove_size_from_filename (filter)
URL with the -WIDTHxHEIGHT size suffix removed, used to match a sized image back to its attachment.
apply_filters( 'wpmcs_remove_size_from_filename', string $url );
4. Uploads and image sizes
wpmcs_do_update_attachment_metadata (action, trigger)
Fire this to (re)upload an attachment and all its sizes using the current settings.
do_action( 'wpmcs_do_update_attachment_metadata', false, int $attachment_id );
<em>// After your plugin regenerates an image, push it to the cloud again.</em>
do_action( 'wpmcs_do_update_attachment_metadata', false, $attachment_id );
wpmcs_do_reupload_media (filter)
Return true to force every file of an attachment to be re-uploaded, even if it already exists in the bucket.
apply_filters( 'wpmcs_do_reupload_media', bool $reupload = false, int $attachment_id, string $source_type );
wpmcs_upload_attachment_image_sizes (filter)
Image sizes that will be uploaded for an attachment.
apply_filters( 'wpmcs_upload_attachment_image_sizes', array $sizes, int $attachment_id, array $attachment_meta );
<em>// Don't offload the 'tiny-thumb' size.</em>
add_filter( 'wpmcs_upload_attachment_image_sizes', function ( $sizes ) {
unset( $sizes['tiny-thumb'] );
return $sizes;
} );
wpmcs_skip_upload_image_sizes (filter)
Return true to skip uploading all generated image sizes for this attachment (the main file is still uploaded). Runs before wpmcs_upload_attachment_image_sizes.
apply_filters( 'wpmcs_skip_upload_image_sizes', bool $skip = false, int $attachment_id, array $attachment_meta );
wpmcs_wait_for_generate_attachment_metadata (filter)
Return true to delay the upload until WordPress has finished generating every image sub-size. This is useful if another plugin creates sizes asynchronously.
apply_filters( 'wpmcs_wait_for_generate_attachment_metadata', bool $wait = false );
wpmcs_update_attached_file (filter)
File path when a synced attachment’s file is replaced through update_attached_file().
apply_filters( 'wpmcs_update_attached_file', string $file, int $attachment_id, array $item );
5. Local file access
When Remove files from server is on, get_attached_file() can’t return a local path. These hooks control what code that needs a local file gets instead. See Making Your Plugin Cloud-Aware.
wpmcs_get_attached_file (filter)
Value returned by get_attached_file() for a synced item whose local file is missing. The default is the cloud URL. A late fallback (priority 999) swaps it for a read-only stream path (wpmcssw://bucket/key) that PHP file functions can read.
apply_filters( 'wpmcs_get_attached_file', string $url, string $file, int $attachment_id, array $item );
wpmcs_get_attached_file_noop (filter)
Same as above, but runs when the local file does exist.
apply_filters( 'wpmcs_get_attached_file_noop', string $file, string $file, int $attachment_id, array $item );
wpmcs_get_attached_file_copy_back_to_server (filter)
Return true to download the file back to the server before it’s returned, so it’s a real local file. If the download fails, the cloud URL is returned instead.
apply_filters( 'wpmcs_get_attached_file_copy_back_to_server', bool $copy = false, string $file, int $attachment_id, array $item );
<em>// Our PDF generator needs real local files.</em>
add_filter( 'wpmcs_get_attached_file_copy_back_to_server', function ( $copy ) {
return doing_action( 'my_pdf_generate' ) ? true : $copy;
} );
wpmcs_rest_api_enable_get_attached_file_copy_back_to_server / wpmcs_rest_api_enable_get_attached_file_remove_from_server (filters)
REST route patterns (regular expressions) during which offloaded files are copied back to the server, and cleaned up again afterwards. The default includes Regenerate Thumbnails’ route.
apply_filters( 'wpmcs_rest_api_enable_get_attached_file_copy_back_to_server', array $routes );
apply_filters( 'wpmcs_rest_api_enable_get_attached_file_remove_from_server', array $routes );
$route = '/my-plugin/v\d+/process/';
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 ] ) );
6. Server and cloud cleanup
wpmcs_files_to_remove_from_server (filter)
Local files about to be deleted after upload (when Remove files from server is on). Remove paths from the array to keep them.
apply_filters( 'wpmcs_files_to_remove_from_server', array $files, int $source_id, array $item );
<em>// Always keep the full-size original on the server.</em>
add_filter( 'wpmcs_files_to_remove_from_server', function ( $files, $id ) {
$main = get_attached_file( $id, true );
return array_values( array_diff( $files, [ $main ] ) );
}, 10, 2 );
wpmcs_pre_update_item_additional_files_to_remove_from_server (filter)
Extra local files to delete when an item is about to be updated.
apply_filters( 'wpmcs_pre_update_item_additional_files_to_remove_from_server', array $files = [], int $source_id, array $new_item, array $old_item, string $source_type );
wpmcs_should_delete_cloud_files (filter)
Whether an item’s cloud objects are deleted when the item is removed. Return false to keep them in the bucket.
apply_filters( 'wpmcs_should_delete_cloud_files', bool $delete = true, array $item );
wpmcs_remove_server_files_after_item_update (filter)
Whether an item’s local files may be removed after its record is updated, when Remove files from server is on. Return false to keep them for that update.
apply_filters( 'wpmcs_remove_server_files_after_item_update', bool $remove = true, int $source_id, string $source_type );
wpmcs_files_replaced (action)
Fired when an item’s files in the bucket were uploaded again under the same names. CDN Cache Purge PRO uses it to purge them. Use it to clear your own caches.
do_action( 'wpmcs_files_replaced', int $source_id, string $source_type );
wpmcs_bucket_policy_statements (filter)
Statements of the public-read bucket policy that Private Media writes on Amazon S3 and DigitalOcean Spaces. Add your own statements here so they survive Apply Policy.
apply_filters( 'wpmcs_bucket_policy_statements', array $statements, string $bucket, string $private_prefix );
wpmcs_private_media_apply_result (filter) PRO
Result of applying the private path’s bucket policy, before it’s saved and returned to the admin.
apply_filters( 'wpmcs_private_media_apply_result', array $result, string $prefix );
7. Item lifecycle
wpmcs_get_item (filter)
A synced-item row each time it’s read. Returns false when the source isn’t synced.
apply_filters( 'wpmcs_get_item', array|false $item, int $source_id, string $source_type );
wpmcs_pre_update_item (action)
Fires before an item’s record is updated (for example on re-upload).
do_action( 'wpmcs_pre_update_item', int $source_id, array $new_item, array $old_item, string $source_type );
wpmcs_post_update_item (action)
Fires after an item is uploaded or updated.
do_action( 'wpmcs_post_update_item', int $source_id, array $data, string $source_type );
<em>// Purge a page cache when an image finishes syncing.</em>
add_action( 'wpmcs_post_update_item', function ( $id ) {
if ( $parent = wp_get_post_parent_id( $id ) ) {
clean_post_cache( $parent );
}
} );
8. Background jobs
Fired by bulk jobs. {$type} is the job’s identifier, such as sync_to_cloud.
do_action( "wpmcs_{$type}_started", string $type );
do_action( "wpmcs_{$type}_completed", string $type );
do_action( "wpmcs_{$type}_cancelled", string $type );
add_action( 'wpmcs_sync_to_cloud_completed', function () {
wp_mail( get_option( 'admin_email' ), 'Media sync finished', 'All media has been offloaded.' );
} );
9. Settings
wpmcs_validate_settings_save (filter)
Validates settings before they’re saved from the admin. Return ['ok' => false, 'message' => '…'] to block the save and show the message.
apply_filters( 'wpmcs_validate_settings_save', array $result = [ 'ok' => true, 'message' => '' ], array $settings, string $action );
wpmcs_after_settings_save (action)
Fires after settings are saved from the admin.
do_action( 'wpmcs_after_settings_save', array $settings, string $action );
wpmcs_settings_transfer_secret_keys (filter)
Setting keys kept out of settings exports and never overwritten by imports. Add keys your own code stores secrets under.
apply_filters( 'wpmcs_settings_transfer_secret_keys', array $keys );
wpmcs_settings_transfer_bucket_keys (filter)
Setting keys that belong to one bucket, such as the delivery domain. They’re only imported from a file exported for the same bucket.
apply_filters( 'wpmcs_settings_transfer_bucket_keys', array $keys );
10. Access control
See wpmcs_should_serve_from_cloud, wpmcs_generate_private_url, and wpmcs_private_object_key_root above.
11. Miscellaneous
wpmcs_create_plugin_dir (action)
Fires after the plugin’s working folder (wp-content/uploads/wpmcs_uploads/) is recreated during a reset.
do_action( 'wpmcs_create_plugin_dir' );
wpmcs_imagify_is_provider_url (filter)
Imagify compatibility: return true/false to decide whether a URL belongs to the cloud provider (null = let the plugin decide).
apply_filters( 'wpmcs_imagify_is_provider_url', ?bool $is_provider = null, string $url );
wpmcs_import_bucket_expected_files (filter) PRO
Extra files Import from Bucket should look for with a Media Library item, for example a plugin’s WebP copies.
apply_filters( 'wpmcs_import_bucket_expected_files', array $files = [], int $attachment_id, array $expected, array $meta );
wpmcs_import_bucket_extras (filter) PRO
Extra data stored on the record Import from Bucket creates for an item.
apply_filters( 'wpmcs_import_bucket_extras', array $extras, int $attachment_id, array $found, array $expected );
12. Admin UI schema
The plugin’s admin screens (dashboard cards, setup wizard, provider and delivery options, settings fields, bulk job screens, header menu) are built from a schema assembled in PHP and printed into the admin page. You can change most of it with filters; no JavaScript is needed.
wpmcs_ui_schema_{$section} (filter)
Filters one section of the schema.
apply_filters( "wpmcs_ui_schema_{$section}", array $data );
| Section | Contents |
|---|---|
dashboard_cards | Cards on the dashboard: label, description, slug, link, icon (URL), iconBgColor, external, requires ('service' or 'operational'). |
dashboard_pro_cards | Second card row (shown only when it has entries). |
services | Storage providers and their wizard steps and storage settings fields. |
cdnServers | Delivery options per storage provider, with their fields. |
settingsDefaultValues | Default value of every setting, per provider. |
syncScreen | Bulk job screens, keyed by job type (see below). |
nav | Header menu items: label, path, external, requires. |
routes | Paths of the plugin’s own custom pages that are enabled. |
syncMethods | Bulk sync methods (value, label, description, locked, default). |
deliveryResetKeys | Setting keys reset to defaults when the delivery option changes. |
welcome | Setup wizard Welcome step content. |
configure_progress_bar, configure_footer, configureDefaultValues, bucketDefaultValues, bucketAddNewDefaultValues | Setup wizard internals. |
<em>// Add a dashboard card that links to your own admin page.</em>
add_filter( 'wpmcs_ui_schema_dashboard_cards', function ( $cards ) {
$cards[] = [
'label' => 'Image Audit',
'description' => 'Review unoptimized images',
'slug' => 'image_audit',
'link' => admin_url( 'admin.php?page=my-image-audit' ),
'external' => true,
'icon' => plugins_url( 'icons/audit.svg', __FILE__ ),
'iconBgColor' => '#E4F0FF',
];
return $cards;
} );
wpmcs_ui_schema_settings_fields / wpmcs_ui_schema_delivery_fields (filters)
Fields on the Settings page: the Storage Settings column (per provider) and the Delivery Settings column (per delivery option). They run after the section filters, so they also apply to providers and delivery options added through them.
apply_filters( 'wpmcs_ui_schema_settings_fields', array $fields, string $service );
apply_filters( 'wpmcs_ui_schema_delivery_fields', array $fields, string $service, string $delivery_key, array $entry );
A field is label, desc, name (setting key), type (toggle, text, number, select, tags), and optionally childrens (fields shown while a toggle is on), options (for select), placeholder, required, and warning (['enable' => true, 'message' => '<p>…</p>'], a confirmation shown when the toggle is turned on).
Values are saved with the plugin’s other settings and can be read with \Dudlewebs\WPMCS\Utils::get_settings( 'your_key' ). Validate them with wpmcs_validate_settings_save.
<em>// Add a toggle to every provider's storage settings…</em>
add_filter( 'wpmcs_ui_schema_settings_fields', function ( $fields ) {
$fields[] = [
'label' => 'Keep full-size files on the server',
'desc' => 'When removing files from the server, keep the main file and only remove generated sizes.',
'name' => 'my_keep_full_size',
'type' => 'toggle',
];
return $fields;
} );
<em>// …and act on it.</em>
add_filter( 'wpmcs_files_to_remove_from_server', function ( $files, $id ) {
if ( ! \Dudlewebs\WPMCS\Utils::get_settings( 'my_keep_full_size' ) ) {
return $files;
}
return array_values( array_diff( $files, [ get_attached_file( $id, true ) ] ) );
}, 10, 2 );
Field actions. A field can carry an action block, rendered under it as an Apply/Remove panel that calls one of the plugin’s REST endpoints and shows a stored status. It’s used for settings that also need a one-time change on the bucket.
wpmcs_ui_schema (filter)
The whole schema, after every section and field filter. Prefer the section filters; if this filter returns something that can’t be encoded, the page falls back to the schema without it.
apply_filters( 'wpmcs_ui_schema', array $schema );
Job screens
syncScreen entries describe the screens of the plugin’s bulk jobs: title, description, path (the screen’s URL), and optionally confirm (a dialog with toggle options shown before START), retry, requiresKnownTotal, and syncMethods. Job types themselves are registered internally, so a new entry only works for job types the plugin provides.
Limits
- New field types and new kinds of pages need changes to the plugin’s admin app; the schema can only use the existing ones.
- Malformed entries (for example a card without
slug,labelandlink, or a menu item withoutlabelandpath) are dropped.