Helper API and Data Model
Helper API
Synced items are managed by the Item singleton:
use Dudlewebs\WPMCS\Item;
$items = Item::instance();
All methods take a $source_type, which is 'media_library' for attachments. Pro adds its own, such as 'wc_downloadable' for WooCommerce downloadable files and 'edd_download_file' for Easy Digital Downloads, plus source types for BuddyBoss avatars and cover photos.
get( int $source_id, string $source_type = 'media_library' ): array|false
Returns the synced-item row for the currently connected bucket, or false if the source isn’t synced there. Results are cached.
$item = Item::instance()->get( $attachment_id );
if ( $item ) {
echo $item['key']; <em>// wp-content/uploads/2026/10/photo.jpg</em>
echo $item['provider']; <em>// s3, gcloud, docean, cloudflareR2, s3compatible</em>
}
get_url( int $source_id, string $size = 'full', string $source_type = 'media_library' ): string|false
The cloud URL for a file. $size is 'full', 'original' (the pre-scaled original, when WordPress kept one), or a registered image size name.
$thumb = Item::instance()->get_url( $attachment_id, 'thumbnail' );
In templates, prefer
wp_get_attachment_image_src(). It respects delivery settings and falls back to the local URL when needed.
is_available_from_provider( int $attachment_id, bool $check_rewrite = true, string $source_type = 'media_library' ): bool
true when the item is synced to the connected bucket. With $check_rewrite = true (default), it also requires Deliver Synced Media to be on, meaning the item is actually served from the cloud.
if ( Item::instance()->is_available_from_provider( $attachment_id ) ) {
<em>// URLs for this attachment point to the cloud.</em>
}
get_extras( int $source_id, string|false $field = false, string $source_type = 'media_library' ): mixed
Decoded extra data for an item (see below). Pass a field name to get just that field, such as 'sizes'.
$sizes = Item::instance()->get_extras( $attachment_id, 'sizes' );
<em>// [ 'thumbnail' => [ 'key' => '…-150x150.jpg', … ], 'medium' => [ … ] ]</em>
Detecting the plugin
$active = defined( 'WPMCS_VERSION' ) && class_exists( '\Dudlewebs\WPMCS\Item' );
Data model
Items table
Each synced source file has one row per bucket in {$wpdb->prefix}wpmcs_items. On multisite it’s per site: {$wpdb->get_blog_prefix()}wpmcs_items.
| Column | Type | Description |
|---|---|---|
id | BIGINT | Row ID. |
provider | VARCHAR(18) | s3, gcloud, docean, cloudflareR2, or s3compatible. |
region | VARCHAR(255) | Bucket region (may be empty). |
storage | VARCHAR(255) | Bucket name. |
source_id | BIGINT | Source object ID (the attachment ID for Media Library items). |
source_type | VARCHAR(18) | Source kind, such as media_library. |
source_path | VARCHAR(1024) | File path relative to the uploads directory, such as 2026/10/photo.jpg. |
url | VARCHAR(1024) | Cloud URL of the main file at upload time. |
key | VARCHAR(1024) | Object key of the main file in the bucket. |
original_source_path | VARCHAR(1024) | Relative path of the pre-scaled original (if any). |
original_key | VARCHAR(1024) | Object key of the pre-scaled original (if any). |
is_private | TINYINT(1) | 1 when the object is stored as private. |
extra | LONGTEXT | Serialized array: image sizes (sizes → per-size key/source_path), backup files, and other per-item data. |
Rows are matched on source_id + source_type + provider + storage (+ region). Switching to a different bucket means items have no row for the new bucket until they’re synced there.
Read, don’t write. Always go through Item::instance(). Reads are cached, and direct INSERT/UPDATEs will desynchronize the cache and the plugin’s state.
Options
Settings and credentials are stored in the wpmcs_global_settings option. Treat it as internal: its structure changes between versions, and credentials may be supplied by WPMCS_CONFIG instead. Use the hooks in this documentation rather than reading or writing the option.