Metadata Storage Architecture

Purpose and Scope

This document describes how BuddyPress VIP Go stores media metadata in the WordPress database instead of relying on filesystem directory structures. It covers the metadata keys used, data structures stored, storage locations (user meta, group meta, options), and multisite blog switching logic.

For information about how files are uploaded and stored in VIP File Hosting Service, see VIP File Hosting Service Integration. For information about how this metadata is used to generate dynamic image URLs, see Dynamic Image Processing and URL Generation.

Core Design Principle

The plugin implements a metadata-driven transformation model. Unlike standard WordPress media handling, which pre-generates multiple image sizes and stores them as files, this plugin stores:

1. One original file in VIP File Hosting Service (FHS)
2. Transformation metadata in the WordPress database (crop coordinates, UI width)
3. Dynamic URLs with query parameters for on-demand transformations

This approach eliminates the need for BuddyPress to scan filesystem directories, which is incompatible with VIP Go's distributed file system.

Sources: files.php1-967 README.md24-42

Metadata Keys Overview

The plugin uses five distinct metadata keys to store media information:

Metadata Key	Storage Location	Object Type	Media Type	Data Stored
vipbp-avatars	User Meta	User	Avatar	url, crop_x, crop_y, crop_w, crop_h, ui_width
vipbp-user-cover	User Meta	User	Cover Image	url only
vipbp-group-avatars	Group Meta	Group	Avatar	url, crop_x, crop_y, crop_w, crop_h, ui_width
vipbp-group-cover	Group Meta	Group	Cover Image	url only
vipbp-default-group-avatar	Options Table	Global	Default Avatar	url, crop_x, crop_y, crop_w, crop_h, ui_width

Sources: files.php81-82 files.php117-120 files.php289-295 files.php402-434 files.php518-529 files.php610-627 README.md32-36

Metadata Storage by Media Type

Avatar Metadata Structure

Avatars store comprehensive metadata because users can crop them to different coordinates:

Field Purposes:

• url - Points to original uploaded file in VIP FHS
• crop_x, crop_y, crop_w, crop_h - User-selected crop coordinates from cropper UI
• ui_width - Width of the upload interface when image was uploaded (prevents upscaling mobile uploads)

Initial Values on Upload: files.php402-413 files.php416-434 files.php518-529

• Crop values default to full avatar dimensions: bp_core_avatar_full_width() and bp_core_avatar_full_height()
• Crop position defaults to (0, 0)
• ui_width set to $crop_image_width (clamped to available UI width)

Updated Values on Crop: files.php679-738

• Only crop coordinates updated: crop_x, crop_y, crop_w, crop_h
• URL and ui_width remain unchanged

Sources: files.php402-434 files.php518-529 files.php679-738 files.php221-244

Cover Image Metadata Structure

Cover images use minimal metadata because they have a fixed crop pattern:

Why Only URL?

Cover images always crop the middle 25% of the image vertically (files.php307), so crop coordinates don't need to be stored. The cropping is applied dynamically via query parameters when the image is retrieved.

Sources: files.php277-323 files.php562-648 files.php610-627 README.md33-35

Storage Locations and Functions

User Metadata Storage

User Avatar Functions:

• Write: files.php402-413 (update_user_meta)
• Write Webcam: files.php518-529 (update_user_meta)
• Update Crop: files.php695-706 (update_user_meta)
• Read: files.php81 (get_user_meta)
• Delete: files.php810-811 (delete_user_meta)

User Cover Functions:

• Write: files.php610-617 (update_user_meta)
• Read: files.php289 (get_user_meta)
• Delete: files.php857-858 (delete_user_meta)

Sources: files.php70-89 files.php336-464 files.php476-545 files.php679-738 files.php761-836 files.php847-875

Group Metadata Storage

Group Avatar Functions:

• Write: files.php429-433 (groups_update_groupmeta)
• Update Crop: files.php713 files.php730 (groups_update_groupmeta)
• Read: files.php120 (groups_get_groupmeta)
• Delete: files.php819-820 (groups_delete_groupmeta)

Group Cover Functions:

• Write: files.php619-626 (groups_update_groupmeta)
• Read: files.php294 (groups_get_groupmeta)
• Delete: files.php861-862 (groups_delete_groupmeta)

Sources: files.php106-136 files.php415-435 files.php619-626 files.php708-731 files.php813-821 files.php860-862

Default Group Avatar (Options Table)

The default group avatar (used when item_id=0) requires special handling because it doesn't belong to any specific group:

Why Options Instead of Group Meta?

Group metadata functions require a valid group ID. Since the default group avatar doesn't belong to a specific group, it's stored in the options table instead.

Functions:

• Write: files.php426-427 (bp_update_option)
• Update Crop: files.php728 (bp_update_option)
• Read: files.php117 files.php125 (bp_get_option)
• Delete: files.php817 (bp_delete_option)
• Filter for BuddyBoss: files.php941-946 files.php958-965 (bp_get_option)

Fallback Logic: files.php122-126

If a group has no specific avatar, the system falls back to the default group avatar.

Sources: files.php114-127 files.php425-427 files.php710-711 files.php726-728 files.php815-817 files.php927-966

Multisite Blog Switching

All metadata is stored on the root blog in multisite installations to centralize management and avoid data fragmentation across network sites.

Blog Switching Pattern

Implementation in Functions

Every function that reads or writes metadata follows this pattern:

$switched = false;

if ( ! bp_is_root_blog() ) {
 switch_to_blog( bp_get_root_blog_id() );
 $switched = true;
}

// Perform metadata operations

if ( $switched ) {
 restore_current_blog();
}

Functions Using This Pattern:

Function	Lines
vipbp_filter_user_avatar_urls	files.php71-86
vipbp_filter_group_avatar_urls	files.php108-133
vipbp_filter_avatar_urls	files.php150-253
vipbp_filter_get_cover_image	files.php282-321
vipbp_handle_avatar_upload	files.php338-461
vipbp_handle_avatar_capture	files.php483-542
vip_handle_cover_image_upload	files.php564-646
vipbp_handle_avatar_crop	files.php688-736
vipbp_delete_existing_avatar	files.php765-833
vipbp_delete_cover_image	files.php851-873

Sources: files.php71-86 files.php108-133 files.php150-253 files.php282-321 files.php338-461 files.php483-542 files.php564-646 files.php688-736 files.php765-833 files.php851-873

Metadata Lifecycle

Avatar Upload and Crop Lifecycle

Sources: files.php336-464 files.php476-545 files.php679-738 files.php761-836

Cover Image Lifecycle

Sources: files.php562-648 files.php847-875

Code Entity Reference

Functions That Write Metadata

Function	Metadata Key(s)	Storage Function	Lines
vipbp_handle_avatar_upload	vipbp-avatars, vipbp-group-avatars, vipbp-default-group-avatar	update_user_meta, groups_update_groupmeta, bp_update_option	files.php336-464
vipbp_handle_avatar_capture	vipbp-avatars	update_user_meta	files.php476-545
vip_handle_cover_image_upload	vipbp-user-cover, vipbp-group-cover	update_user_meta, groups_update_groupmeta	files.php562-648
vipbp_handle_avatar_crop	vipbp-avatars, vipbp-group-avatars, vipbp-default-group-avatar	update_user_meta, groups_update_groupmeta, bp_update_option	files.php679-738

Functions That Read Metadata

Function	Metadata Key(s)	Storage Function	Lines
vipbp_filter_user_avatar_urls	vipbp-avatars	get_user_meta	files.php70-89
vipbp_filter_group_avatar_urls	vipbp-group-avatars, vipbp-default-group-avatar	groups_get_groupmeta, bp_get_option	files.php106-136
vipbp_filter_avatar_urls	(receives meta from above)	N/A	files.php148-256
vipbp_filter_get_cover_image	vipbp-user-cover, vipbp-group-cover	get_user_meta, groups_get_groupmeta	files.php277-323
vipbp_filter_default_group_avatar_option	vipbp-default-group-avatar	bp_get_option	files.php941-946
vipbp_filter_bb_default_group_avatar	vipbp-default-group-avatar	bp_get_option	files.php958-965

Functions That Delete Metadata

Function	Metadata Key(s)	Storage Function	Lines
vipbp_delete_existing_avatar	vipbp-avatars, vipbp-group-avatars, vipbp-default-group-avatar	delete_user_meta, groups_delete_groupmeta, bp_delete_option	files.php761-836
vipbp_delete_cover_image	vipbp-user-cover, vipbp-group-cover	delete_user_meta, groups_delete_groupmeta	files.php847-875

Sources: files.php1-967

Data Validation and Error Handling

Empty Metadata Checks

Functions validate metadata before use:

Avatar URL Retrieval: files.php163-214

• If $meta is empty or $meta['url'] is empty, return Gravatar fallback
• Prevents broken images when no avatar uploaded

Crop Operation Validation: files.php697-703 files.php716-722

• Don't update crop values if $meta['url'] is empty
• Prevents storing crop coordinates for failed uploads

Deletion Safety: files.php824-829 files.php865-868

• Only call wp_delete_file() if $meta exists
• Prevents errors when deleting non-existent files

Group Avatar Fallback

files.php122-126

If a group has no specific avatar, fall back to default group avatar:

Sources: files.php163-214 files.php697-703 files.php716-722 files.php824-829 files.php865-868 files.php122-126

BuddyBoss-Specific Metadata Handling

BuddyBoss adds additional default group avatar functionality that requires special metadata handling to avoid opendir() filesystem calls:

Implementation Details:

1. Option Filter: files.php20 files.php941-946

   • Filters option_bp-default-custom-group-avatar
   • Returns empty string if VIP metadata exists
   • This prevents BuddyBoss from calling bb_get_default_custom_avatar()

2. Avatar URL Filter: files.php21 files.php958-965

   • Filters bb_get_default_custom_upload_group_avatar
   • Provides actual avatar URL from vipbp-default-group-avatar metadata

Sources: files.php20-21 files.php927-966

Summary

The metadata storage architecture enables BuddyPress media functionality on VIP Go by:

1. Avoiding filesystem operations - All media information stored in database
2. Enabling dynamic transformations - Crop coordinates stored, not pre-generated images
3. Centralizing data - All metadata on root blog in multisite
4. Maintaining compatibility - Special handling for default group avatars and BuddyBoss

This design trades storage for compute, leveraging VIP FHS's dynamic image manipulation capabilities to reduce database and file storage requirements.

Sources: files.php1-967 README.md1-62