Skip to content
Black Friday

20% off for every Pro licenses

BLACKFRIDAYClaim the Offer
Contact us

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.

ColumnTypeDescription
idBIGINTRow ID.
providerVARCHAR(18)s3, gcloud, docean, cloudflareR2, or s3compatible.
regionVARCHAR(255)Bucket region (may be empty).
storageVARCHAR(255)Bucket name.
source_idBIGINTSource object ID (the attachment ID for Media Library items).
source_typeVARCHAR(18)Source kind, such as media_library.
source_pathVARCHAR(1024)File path relative to the uploads directory, such as 2026/10/photo.jpg.
urlVARCHAR(1024)Cloud URL of the main file at upload time.
keyVARCHAR(1024)Object key of the main file in the bucket.
original_source_pathVARCHAR(1024)Relative path of the pre-scaled original (if any).
original_keyVARCHAR(1024)Object key of the pre-scaled original (if any).
is_privateTINYINT(1)1 when the object is stored as private.
extraLONGTEXTSerialized 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.