VIP File Hosting Service Integration

This document describes how the plugin integrates with WordPress VIP's File Hosting Service (VIP FHS), including file upload mechanisms, dynamic image transformation via query parameters, CDN delivery, and file deletion operations. The VIP FHS is a distributed storage system that replaces WordPress's standard filesystem operations.

For information about the metadata stored alongside files, see Metadata Storage Architecture. For details on how query parameters enable image transformations, see Dynamic Image Processing and URL Generation.

VIP File Hosting Service Overview

VIP Go's File Hosting Service is a distributed, CDN-backed storage system that does not support standard filesystem operations like opendir(), flock(), or directory traversal. The plugin bridges BuddyPress's filesystem expectations with VIP FHS capabilities by:

1. Using WordPress's upload APIs (wp_handle_upload, wp_handle_sideload, wp_upload_bits) which VIP FHS automatically intercepts
2. Storing only original files in VIP FHS
3. Generating transformed versions on-demand via query parameters
4. Delegating CDN caching and delivery to VIP infrastructure

Key Architectural Principle: The plugin never directly manipulates the filesystem. All operations go through WordPress APIs that VIP FHS hooks into.

Sources: files.php1-10 README.md13-22

File Upload Integration Architecture

Upload Flow Diagram

Sources: files.php336-649 README.md24-42

Standard File Upload: wp_handle_sideload

Avatars uploaded via standard form submissions use wp_handle_sideload() instead of wp_handle_upload() for consistency with webcam captures and because BuddyPress has already validated the upload upstream.

The key code section handles the upload:

files.php362-380

• Line 362: Store uploaded file info
• Line 363-369: Call wp_handle_sideload() with test_form=false because BuddyPress already validated
• Line 371-380: Handle errors and display user-facing messages

Why wp_handle_sideload instead of wp_handle_upload: The choice is documented in code comments - BuddyPress has already validated the upload, and using wp_handle_sideload maintains consistency with webcam capture handling.

Sources: files.php336-464 files.php362-369

Webcam Capture: wp_upload_bits

Webcam avatars are base64-decoded PNG data, not form uploads. The plugin uses wp_upload_bits() which writes directly to the filesystem without requiring a temporary file.

Key implementation details at files.php489-504:

• Line 491: Generate secure filename with wp_generate_password(6, false)
• Line 492: Call wp_upload_bits() with null test (no MIME validation needed for PNG)
• Line 495: Immediately free memory with unset($data) to handle large images

Memory Efficiency: The function explicitly calls unset($data) after upload to free memory, as webcam images can be large and memory is not automatically freed until function return.

Sources: files.php476-545 files.php489-504

Cover Image Upload: wp_handle_upload

Cover images use the standard wp_handle_upload() function, matching WordPress Core's upload action to ensure VIP fileservice filters are applied correctly.

files.php576-586

• Line 578: Access $_FILES['file'] directly (already validated upstream)
• Line 579-585: Call wp_handle_upload() with action => 'wp_handle_upload' to match Core
• Line 583: Set test_form => false because BuddyPress validated upload

Sources: files.php562-649 files.php576-586

Video Upload Special Case: Local Temp Directory

Problem: flock() Incompatibility

BuddyBoss's chunked video upload mechanism requires file locking (flock()) to safely assemble video chunks. VIP FHS does not support flock() on distributed storage.

Sources: files.php909-925 README.md43-47

Two-Stage Upload Strategy

Implementation at files.php923-925:

function vipbp_filter_chunked_upload_temp_dir() {
 return get_temp_dir() . 'bb-large-upload';
}

This filter is hooked to bfu_temp_dir at files.php48

How it works:

1. BuddyBoss chunks are written to /tmp/bb-large-upload/ (local filesystem)
2. File locking works in local temp directory
3. After assembly completes, BuddyBoss's own code moves the final file to VIP FHS
4. Cleanup handled by vipbp_override_remove_temp_directory() at files.php886-897

Cache Invalidation: After video moves, vipbp_flush_cache_after_video_move() at files.php905-907 invalidates cached media data via bp_core_reset_incrementor('bp_media').

Sources: files.php909-925 files.php886-897 files.php905-907 files.php23-52

Dynamic URL Construction and Query Parameters

VIP FHS provides Photon-like image transformation via query parameters. The plugin constructs URLs that instruct VIP FHS to transform images on-the-fly.

Query Parameter Reference

Parameter	Purpose	Example	Used For
w	Constrain width, prevent upscaling	w=450	Avatars uploaded on mobile devices
crop	Crop rectangle in pixels	crop=100px,50px,300px,300px	All avatars and cover images
resize	Final output dimensions	resize=150,150	Avatars (bpthumb/bpfull sizes)
strip	Remove metadata	strip=info	All images (EXIF/IPTC removal)

Sources: files.php221-256 files.php301-313

Avatar URL Construction

Avatars require comprehensive transformation parameters because they support user-defined crops.

Implementation at files.php221-256:

• Line 223: Conditionally add w parameter only if ui_width is set (mobile uploads)
• Line 226-232: Build crop parameter from stored coordinates
• Line 235: Build resize parameter for final output size
• Line 238: Add strip=info to remove EXIF/IPTC data
• Line 247: Use urlencode_deep() for proper URL encoding
• Line 248: Apply filter hook for customization
• Line 249: Set URL scheme (http/https)

Why ui_width exists: Images uploaded on narrow mobile displays need width clamping to prevent upscaling artifacts. Desktop uploads set ui_width=0 and the parameter is omitted.

Sources: files.php221-256 files.php148-256

Cover Image URL Construction

Cover images use a simpler parameter set because they follow a fixed crop pattern (middle 25% vertically).

Implementation at files.php301-313:

• Line 304: Width parameter from component dimensions
• Line 307: Fixed crop pattern - always crops from 0,25% vertically
• Line 310: Strip EXIF/IPTC data
• Line 312: Add parameters to metadata URL

No resize parameter: Cover images are displayed at their native dimensions after cropping, unlike avatars which have specific output sizes (bpthumb/bpfull).

Sources: files.php277-324 files.php301-313

CDN Delivery and Transformation Pipeline

Key Behavior:

• First request triggers transformation at FHS
• Result is cached at CDN edge nodes
• Subsequent requests serve from edge cache
• No pre-generation of image sizes occurs
• Storage contains only original files

Cache Invalidation: Changing avatar metadata (new upload, re-crop) generates a new URL, bypassing stale caches. The original file URL remains the same; query parameters change.

Sources: files.php70-89 files.php106-136 files.php148-256 README.md17-20

File Deletion Operations

File deletion is a two-step process: remove metadata, then delete the file via VIP FHS.

Sources: files.php761-836 files.php847-875 README.md41

Avatar Deletion Implementation

files.php808-829

Key operations:

1. Line 810-811: Retrieve metadata to get file URL (users)
2. Line 816-820: Handle default group avatar from option vs group meta
3. Line 824-826: Critical file path processing:
   • strtok($meta['url'], '?') - Remove query parameters
   • str_replace(get_site_url() . '/', '', ...) - Convert absolute URL to relative path
   • wp_delete_file() - VIP FHS intercepts and deletes from distributed storage

Why strip query parameters: The stored URL includes transformation parameters (?w=450&crop=...). The file deletion API requires the base file path without parameters.

Multisite consideration: Always operates on root blog via switch_to_blog() pattern at files.php765-768

Sources: files.php761-836 files.php808-829 files.php765-768

Cover Image Deletion Implementation

Cover image deletion follows the same pattern but with simpler metadata:

files.php856-868

• Line 857-858: Retrieve and delete user cover metadata
• Line 860-862: Retrieve and delete group cover metadata
• Line 865-867: Strip query params, convert to relative path, call wp_delete_file()

Difference from avatars: Cover metadata contains only url key (no crop coordinates), but deletion logic is identical.

Sources: files.php847-875 files.php856-868

VIP FHS Environment Detection

The plugin only activates VIP FHS integration when specific environment markers are present:

These checks occur in the main plugin file. If any check fails, files.php is never loaded and the plugin remains dormant.

Sources: See Plugin Initialization and Environment Detection for complete initialization flow.

Security and Access Control

VIP FHS implements its own security model that the plugin leverages:

1. Upload Security: WordPress's wp_handle_upload() family of functions perform MIME type validation before VIP FHS interception
2. URL Security: VIP FHS URLs use signed tokens (via FILES_ACCESS_TOKEN) to prevent unauthorized access
3. Metadata Isolation: All metadata stored on root blog in multisite, preventing cross-blog data leaks
4. EXIF Stripping: All URLs include strip=info parameter to remove potentially sensitive EXIF/IPTC data

Token Management: The FILES_ACCESS_TOKEN constant is managed by VIP infrastructure and automatically included in VIP FHS requests. The plugin never handles tokens directly.

Sources: files.php238 files.php310 README.md16-20