---
title: "Constants and Configuration"
url: "https://dudlewebs.com/guideline/media-cloud-sync/developers/constants-and-configuration/"
markdown_url: "https://dudlewebs.com/guideline/media-cloud-sync/developers/constants-and-configuration.md"
type: "Docs"
language: "en-US"
date_published: "2026-11-08T11:23:50+00:00"
date_modified: "2026-11-09T17:31:23+00:00"
---

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

**Contents**

1. [Bucket paths and object keys](https://file+.vscode-resource.vscode-cdn.net/Users/rahulk/Documents/Projects/Own%20Projects/Dudlewebs/Plugins/Media%20Cloud%20Sync/App/wp-content/plugins/media-cloud-sync/docs/developer/02-hooks-reference.md#1-bucket-paths-and-object-keys)
2. [URLs and delivery](https://file+.vscode-resource.vscode-cdn.net/Users/rahulk/Documents/Projects/Own%20Projects/Dudlewebs/Plugins/Media%20Cloud%20Sync/App/wp-content/plugins/media-cloud-sync/docs/developer/02-hooks-reference.md#2-urls-and-delivery)
3. [Content URL rewriting](https://file+.vscode-resource.vscode-cdn.net/Users/rahulk/Documents/Projects/Own%20Projects/Dudlewebs/Plugins/Media%20Cloud%20Sync/App/wp-content/plugins/media-cloud-sync/docs/developer/02-hooks-reference.md#3-content-url-rewriting)
4. [Uploads and image sizes](https://file+.vscode-resource.vscode-cdn.net/Users/rahulk/Documents/Projects/Own%20Projects/Dudlewebs/Plugins/Media%20Cloud%20Sync/App/wp-content/plugins/media-cloud-sync/docs/developer/02-hooks-reference.md#4-uploads-and-image-sizes)
5. [Local file access](https://file+.vscode-resource.vscode-cdn.net/Users/rahulk/Documents/Projects/Own%20Projects/Dudlewebs/Plugins/Media%20Cloud%20Sync/App/wp-content/plugins/media-cloud-sync/docs/developer/02-hooks-reference.md#5-local-file-access)
6. [Server and cloud cleanup](https://file+.vscode-resource.vscode-cdn.net/Users/rahulk/Documents/Projects/Own%20Projects/Dudlewebs/Plugins/Media%20Cloud%20Sync/App/wp-content/plugins/media-cloud-sync/docs/developer/02-hooks-reference.md#6-server-and-cloud-cleanup)
7. [Item lifecycle](https://file+.vscode-resource.vscode-cdn.net/Users/rahulk/Documents/Projects/Own%20Projects/Dudlewebs/Plugins/Media%20Cloud%20Sync/App/wp-content/plugins/media-cloud-sync/docs/developer/02-hooks-reference.md#7-item-lifecycle)
8. [Background jobs](https://file+.vscode-resource.vscode-cdn.net/Users/rahulk/Documents/Projects/Own%20Projects/Dudlewebs/Plugins/Media%20Cloud%20Sync/App/wp-content/plugins/media-cloud-sync/docs/developer/02-hooks-reference.md#8-background-jobs)
9. [Settings](https://file+.vscode-resource.vscode-cdn.net/Users/rahulk/Documents/Projects/Own%20Projects/Dudlewebs/Plugins/Media%20Cloud%20Sync/App/wp-content/plugins/media-cloud-sync/docs/developer/02-hooks-reference.md#9-settings)
10. [Access control](https://file+.vscode-resource.vscode-cdn.net/Users/rahulk/Documents/Projects/Own%20Projects/Dudlewebs/Plugins/Media%20Cloud%20Sync/App/wp-content/plugins/media-cloud-sync/docs/developer/02-hooks-reference.md#10-access-control)
11. [Miscellaneous](https://file+.vscode-resource.vscode-cdn.net/Users/rahulk/Documents/Projects/Own%20Projects/Dudlewebs/Plugins/Media%20Cloud%20Sync/App/wp-content/plugins/media-cloud-sync/docs/developer/02-hooks-reference.md#11-miscellaneous)
12. [Admin UI schema](https://file+.vscode-resource.vscode-cdn.net/Users/rahulk/Documents/Projects/Own%20Projects/Dudlewebs/Plugins/Media%20Cloud%20Sync/App/wp-content/plugins/media-cloud-sync/docs/developer/02-hooks-reference.md#12-admin-ui-schema)

---

## 1. Bucket paths and object keys

### `wpmcs_object_key` *(filter)*

Final object key (path inside the bucket) for an uploaded file.

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

```xml
<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.

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

```php
apply_filters( 'wpmcs_object_version_prefix', string $prefix );
```

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

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

```php
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()`.

```php
apply_filters( 'wpmcs_wp_get_attachment_url', string $new_url, string $original_url, int $attachment_id );
```

```xml
<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`.)

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

```php
apply_filters( 'wpmcs_cdn_url', string $new_url, string $provider_url, string $cdn_base_url );
```

```xml
<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.

```xml
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).

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

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

```php
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](https://dudlewebs.com/guideline/media-cloud-sync/developers/making-your-plugin-cloud-aware/#rewriting-urls-in-your-own-content) for when to use which.

```php
$html = apply_filters( 'wpmcs_filter_post', string $content );
```

```xml
<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.

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

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

```php
apply_filters( 'wpmcs_server_domains', array $domains );
apply_filters( 'wpmcs_remote_domains', array $domains );
```

```php
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()`.

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

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

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

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

```php
do_action( 'wpmcs_do_update_attachment_metadata', false, int $attachment_id );
```

```xml
<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.

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

```php
apply_filters( 'wpmcs_upload_attachment_image_sizes', array $sizes, int $attachment_id, array $attachment_meta );
```

```xml
<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`.

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

```php
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()`.

```php
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](https://dudlewebs.com/guideline/media-cloud-sync/developers/making-your-plugin-cloud-aware/#reading-offloaded-files).

### `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.

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

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

```php
apply_filters( 'wpmcs_get_attached_file_copy_back_to_server', bool $copy = false, string $file, int $attachment_id, array $item );
```

```xml
<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.

```php
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 );
```

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

```php
apply_filters( 'wpmcs_files_to_remove_from_server', array $files, int $source_id, array $item );
```

```xml
<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.

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

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

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

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

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

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

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

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

```php
do_action( 'wpmcs_post_update_item', int $source_id, array $data, string $source_type );
```

```xml
<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`.

```php
do_action( "wpmcs_{$type}_started",   string $type );
do_action( "wpmcs_{$type}_completed", string $type );
do_action( "wpmcs_{$type}_cancelled", string $type );
```

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

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

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

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

```php
apply_filters( 'wpmcs_settings_transfer_bucket_keys', array $keys );
```

---

## 10. Access control

See [`wpmcs_should_serve_from_cloud`](https://file+.vscode-resource.vscode-cdn.net/Users/rahulk/Documents/Projects/Own%20Projects/Dudlewebs/Plugins/Media%20Cloud%20Sync/App/wp-content/plugins/media-cloud-sync/docs/developer/02-hooks-reference.md#wpmcs_should_serve_from_cloud-filter), [`wpmcs_generate_private_url`](https://file+.vscode-resource.vscode-cdn.net/Users/rahulk/Documents/Projects/Own%20Projects/Dudlewebs/Plugins/Media%20Cloud%20Sync/App/wp-content/plugins/media-cloud-sync/docs/developer/02-hooks-reference.md#wpmcs_generate_private_url-filter), and [`wpmcs_private_object_key_root`](https://file+.vscode-resource.vscode-cdn.net/Users/rahulk/Documents/Projects/Own%20Projects/Dudlewebs/Plugins/Media%20Cloud%20Sync/App/wp-content/plugins/media-cloud-sync/docs/developer/02-hooks-reference.md#wpmcs_private_object_key_root-filter) 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.

```plain
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).

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

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

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

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

```xml
<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.

```php
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`](https://file+.vscode-resource.vscode-cdn.net/Users/rahulk/Documents/Projects/Own%20Projects/Dudlewebs/Plugins/Media%20Cloud%20Sync/App/wp-content/plugins/media-cloud-sync/docs/developer/02-hooks-reference.md#wpmcs_validate_settings_save-filter).

```xml
<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.

```php
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`, `label` and `link`, or a menu item without `label` and `path`) are dropped.

[← Previous Hooks Reference](https://dudlewebs.com/guideline/media-cloud-sync/developers/hooks-reference/) [Next → Making Your Plugin Cloud-Aware](https://dudlewebs.com/guideline/media-cloud-sync/developers/making-your-plugin-cloud-aware/)

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/)
