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.
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
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:
- Verify that the file exists in the local uploads directory.
- Upload the file to Infinite Uploads cloud storage if it is not already present.
- Update internal caches and state so the file is served from the Infinite Uploads CDN.
- Trigger any relevant filters/actions for plugins that need to hook into the offload process (e.g., optimization plugins).
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 successfully offloaded or already existed in the cloud.false– The file could not be uploaded (missing file, permissions issue, invalid path).
Usage Example
Here’s a typical example of how you might call offload_image() after generating a new optimized or resized image:
$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:
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_pathis relative, not absolute.
Related Filters and Hooks
When offload_image() runs, it aligns with the existing Infinite Uploads offload pipeline, allowing you to hook into:
infinite_uploads_pre_offload_fileinfinite_uploads_post_offload_fileinfinite_uploads_offload_error
(Names may vary depending on your implementation — update these if needed.)
0 Comments