Offloading Images with offload_image()

betterdocs-category-icon

Developers

10

Infinite Uploads provides a helper function, offload_image( $relative_path ), that allows developers and third-party plugins (such as ShortPixel) to programmatically offload any local image to Infinite Uploads cloud storage and ensure it is synced and accessible through the CDN.

Requires Infinite Uploads 3.4.3 or later. On older versions the function doesn’t exist, and calling it causes a “Call to undefined function” error. Wrap the call in function_exists( 'offload_image' ) if your code may run on older versions.

No logged-in user is needed, so you can call it from cron jobs, WP-CLI commands, and other plugins’ hooks.

This function is especially useful for plugins that generate or manipulate image files outside WordPress’s normal upload pipeline and need a reliable way to send those images to Infinite Uploads.

Function Signature

🐘
Copy 
offload_image( string $relative_path )

Parameters

  • $relative_path (string)
    The image’s relative path inside the WordPress uploads directory.
    Example: 2025/01/my-image-800x800.jpg

What the Function Does

Calling offload_image() will:

  1. Check that your site is connected to Infinite Uploads, the file exists in the local uploads directory, the path stays inside the uploads directory, and the file isn’t excluded by your sync exclusion rules.
  2. Upload the file to Infinite Uploads cloud storage.
  3. Mark the file as synced, so a later Sync won’t upload it again.

This hook does not alter WordPress metadata directly—its purpose is to ensure the physical image file is synchronized with its cloud counterpart.

Return Value

offload_image() returns:

  • true – The file was uploaded successfully.
  • false – The site isn’t connected to Infinite Uploads, or the file is missing, invalid, excluded by your sync rules, or failed to upload.

Usage Example

Here’s a typical example of how you might call offload_image() after generating a new optimized or resized image:

🐘
Copy 
$relative_path = '2025/01/my-image-800x800.jpg';

// Offload the file to Infinite Uploads
if ( offload_image( $relative_path ) ) {
    // Success! Continue with your processing.
    error_log( 'Image successfully offloaded: ' . $relative_path );
} else {
    // Something went wrong.
    error_log( 'Failed to offload image: ' . $relative_path );
}

Working With Optimization Plugins (e.g., ShortPixel)

Many optimization plugins generate new image versions or replace originals. Calling offload_image() after these operations guarantees that:

  • The optimized version is available on the Infinite Uploads CDN.
  • Local optimization processes remain fully compatible with Infinite Uploads storage.
  • No additional manual syncing is required.

If you are building compatibility with such plugins, simply trigger offload_image() after the new image file is saved.

Example:

🐘
filename.js
Copy 
add_action( 'shortpixel/image/optimised', function( $image_path ) {
    // Convert absolute path to a relative upload path
    $upload_dir = wp_get_upload_dir();
    $relative_path = str_replace( trailingslashit( $upload_dir['basedir'] ), '', $image_path );

    offload_image( $relative_path );
});

Error Handling & Debugging

If you encounter issues:

  • Ensure the file physically exists in the uploads directory.
  • Confirm that Infinite Uploads is connected and authenticated.
  • Check your PHP error logs for messages generated during the offloading process.
  • Verify that $relative_path is relative, not absolute.
  • Make sure the file isn’t in a folder excluded from sync. Excluded files return false.