---
title: "Helper API and Data Model"
url: "https://dudlewebs.com/guideline/media-cloud-sync/developers/helper-api-and-data-model/"
markdown_url: "https://dudlewebs.com/guideline/media-cloud-sync/developers/helper-api-and-data-model.md"
type: "Docs"
language: "en-US"
date_published: "2026-11-08T11:25:01+00:00"
date_modified: "2026-11-09T17:34:55+00:00"
---

# Helper API and Data Model

## Helper API

Synced items are managed by the `Item` singleton:

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

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

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

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

```xml
$sizes = Item::instance()->get_extras( $attachment_id, 'sizes' );
<em>// [ 'thumbnail' => [ 'key' => '…-150x150.jpg', … ], 'medium' => [ … ] ]</em>
```

### Detecting the plugin

```php
$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`/`UPDATE`s 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`](https://dudlewebs.com/guideline/media-cloud-sync/developers/constants-and-configuration/#wpmcs_config) instead. Use the hooks in this documentation rather than reading or writing the option.

[← Previous Making Your Plugin Cloud-Aware](https://dudlewebs.com/guideline/media-cloud-sync/developers/making-your-plugin-cloud-aware/) [Next → WP-CLI Commands](https://dudlewebs.com/guideline/media-cloud-sync/developers/wp-cli-commands/)

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