{"id":10732,"date":"2025-12-01T16:26:36","date_gmt":"2025-12-01T22:26:36","guid":{"rendered":"https:\/\/infiniteuploads.com\/?post_type=docs&#038;p=10732"},"modified":"2025-12-01T16:40:56","modified_gmt":"2025-12-01T22:40:56","password":"","slug":"offloading-images-with-offload_image","status":"publish","type":"docs","link":"https:\/\/infiniteuploads.com\/docs\/developers\/offloading-images-with-offload_image\/","title":{"rendered":"Offloading Images with offload_image()"},"content":{"rendered":"<!DOCTYPE html PUBLIC \"-\/\/W3C\/\/DTD HTML 4.0 Transitional\/\/EN\" \"http:\/\/www.w3.org\/TR\/REC-html40\/loose.dtd\">\n<html><body><p>Infinite Uploads provides a helper function, <code>offload_image( $relative_path )<\/code>, 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.<\/p>\n\n\n\n<p>This function is especially useful for plugins that generate or manipulate image files outside WordPress&rsquo;s normal upload pipeline and need a reliable way to send those images to Infinite Uploads.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"function-signature\">Function Signature<\/h2>\n\n\n\n<div class=\"betterdocs-code-snippet-wrapper theme-light betterdocs-code-snippet-3e1e4b74\" id=\"betterdocs-code-snippet-3e1e4b74\" data-language=\"php\" data-copy-button=\"true\">\n\n            <div class=\"betterdocs-code-snippet-header betterdocs-file-preview-header\">\n        <div class=\"betterdocs-file-preview-left\">\n                            <div class=\"betterdocs-traffic-lights\">\n                    <span class=\"traffic-light traffic-light-red\"><\/span>\n                    <span class=\"traffic-light traffic-light-yellow\"><\/span>\n                    <span class=\"traffic-light traffic-light-green\"><\/span>\n                <\/div>\n            \n            <div class=\"betterdocs-file-info\">\n                                    <div class=\"betterdocs-file-icon\">\n                                                    <span class=\"betterdocs-file-icon-emoji\">&#128024;<\/span>\n                                            <\/div>\n                \n                            <\/div>\n        <\/div>\n\n        <div class=\"betterdocs-file-preview-right\">\n                            <div class=\"betterdocs-code-snippet-copy-container\">\n                    <button class=\"betterdocs-code-snippet-copy-button\" type=\"button\" data-clipboard-target=\"#betterdocs-code-snippet-3e1e4b74 .betterdocs-code-snippet-code code\" aria-label=\"Copy code to clipboard\">\n                        <svg width=\"16\" height=\"16\" viewbox=\"0 0 24 24\" fill=\"none\" xmlns=\"http:\/\/www.w3.org\/2000\/svg\">\n                            <path d=\"M16 1H4C2.9 1 2 1.9 2 3V17H4V3H16V1ZM19 5H8C6.9 5 6 5.9 6 7V21C6 22.1 6.9 23 8 23H19C20.1 23 21 22.1 21 21V7C21 5.9 20.1 5 19 5ZM19 21H8V7H19V21Z\" fill=\"currentColor\"><\/path>\n                        <\/svg>\n                    <\/button>\n                                    <\/div>\n                    <\/div>\n        <\/div>\n    \n    <div class=\"betterdocs-code-snippet-content\">\n        \n        <pre class=\"betterdocs-code-snippet-code language-php\"><code>offload_image( string $relative_path )\n<\/code><\/pre>\n    <\/div>\n<\/div>\n\n<script type=\"text\/javascript\">\ndocument.addEventListener('DOMContentLoaded', function() {\n    \/\/ Initialize copy functionality for this specific snippet\n    const snippet = document.getElementById('betterdocs-code-snippet-3e1e4b74');\n    if (snippet && window.BetterDocsCodeSnippet) {\n        window.BetterDocsCodeSnippet.initCopyButton(snippet);\n    }\n});\n<\/script>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"parameters\"><strong>Parameters<\/strong><\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong><code>$relative_path<\/code><\/strong> <em>(string)<\/em><br>The image&rsquo;s relative path inside the WordPress uploads directory.<br>Example: <code>2025\/01\/my-image-800x800.jpg<\/code><\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"what-the-function-does\">What the Function Does<\/h2>\n\n\n\n<p>Calling <code>offload_image()<\/code> will:<\/p>\n\n\n\n<ol class=\"wp-block-list\">\n<li>Verify that the file exists in the local uploads directory.<\/li>\n\n\n\n<li>Upload the file to Infinite Uploads cloud storage if it is not already present.<\/li>\n\n\n\n<li>Update internal caches and state so the file is served from the Infinite Uploads CDN.<\/li>\n\n\n\n<li>Trigger any relevant filters\/actions for plugins that need to hook into the offload process (e.g., optimization plugins).<\/li>\n<\/ol>\n\n\n\n<p>This hook does <strong>not<\/strong> alter WordPress metadata directly&mdash;its purpose is to ensure the physical image file is synchronized with its cloud counterpart.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"return-value\">Return Value<\/h2>\n\n\n\n<p><code>offload_image()<\/code> returns:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong><code>true<\/code><\/strong> &ndash; The file was successfully offloaded or already existed in the cloud.<\/li>\n\n\n\n<li><strong><code>false<\/code><\/strong> &ndash; The file could not be uploaded (missing file, permissions issue, invalid path).<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"usage-example\">Usage Example<\/h2>\n\n\n\n<p>Here&rsquo;s a typical example of how you might call <code>offload_image()<\/code> after generating a new optimized or resized image:<\/p>\n\n\n\n<div class=\"betterdocs-code-snippet-wrapper theme-light betterdocs-code-snippet-b341c897\" id=\"betterdocs-code-snippet-b341c897\" data-language=\"php\" data-copy-button=\"true\">\n\n            <div class=\"betterdocs-code-snippet-header betterdocs-file-preview-header\">\n        <div class=\"betterdocs-file-preview-left\">\n                            <div class=\"betterdocs-traffic-lights\">\n                    <span class=\"traffic-light traffic-light-red\"><\/span>\n                    <span class=\"traffic-light traffic-light-yellow\"><\/span>\n                    <span class=\"traffic-light traffic-light-green\"><\/span>\n                <\/div>\n            \n            <div class=\"betterdocs-file-info\">\n                                    <div class=\"betterdocs-file-icon\">\n                                                    <span class=\"betterdocs-file-icon-emoji\">&#128024;<\/span>\n                                            <\/div>\n                \n                            <\/div>\n        <\/div>\n\n        <div class=\"betterdocs-file-preview-right\">\n                            <div class=\"betterdocs-code-snippet-copy-container\">\n                    <button class=\"betterdocs-code-snippet-copy-button\" type=\"button\" data-clipboard-target=\"#betterdocs-code-snippet-b341c897 .betterdocs-code-snippet-code code\" aria-label=\"Copy code to clipboard\">\n                        <svg width=\"16\" height=\"16\" viewbox=\"0 0 24 24\" fill=\"none\" xmlns=\"http:\/\/www.w3.org\/2000\/svg\">\n                            <path d=\"M16 1H4C2.9 1 2 1.9 2 3V17H4V3H16V1ZM19 5H8C6.9 5 6 5.9 6 7V21C6 22.1 6.9 23 8 23H19C20.1 23 21 22.1 21 21V7C21 5.9 20.1 5 19 5ZM19 21H8V7H19V21Z\" fill=\"currentColor\"><\/path>\n                        <\/svg>\n                    <\/button>\n                                    <\/div>\n                    <\/div>\n        <\/div>\n    \n    <div class=\"betterdocs-code-snippet-content\">\n        \n        <pre class=\"betterdocs-code-snippet-code language-php\"><code>$relative_path = '2025\/01\/my-image-800x800.jpg';\n\n\/\/ Offload the file to Infinite Uploads\nif ( offload_image( $relative_path ) ) {\n    \/\/ Success! Continue with your processing.\n    error_log( 'Image successfully offloaded: ' . $relative_path );\n} else {\n    \/\/ Something went wrong.\n    error_log( 'Failed to offload image: ' . $relative_path );\n}\n<\/code><\/pre>\n    <\/div>\n<\/div>\n\n<script type=\"text\/javascript\">\ndocument.addEventListener('DOMContentLoaded', function() {\n    \/\/ Initialize copy functionality for this specific snippet\n    const snippet = document.getElementById('betterdocs-code-snippet-b341c897');\n    if (snippet && window.BetterDocsCodeSnippet) {\n        window.BetterDocsCodeSnippet.initCopyButton(snippet);\n    }\n});\n<\/script>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"working-with-optimization-plugins-e-g-shortpixel-\">Working With Optimization Plugins (e.g., ShortPixel)<\/h2>\n\n\n\n<p>Many optimization plugins generate new image versions or replace originals. Calling <code>offload_image()<\/code> after these operations guarantees that:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>The optimized version is available on the Infinite Uploads CDN.<\/li>\n\n\n\n<li>Local optimization processes remain fully compatible with Infinite Uploads storage.<\/li>\n\n\n\n<li>No additional manual syncing is required.<\/li>\n<\/ul>\n\n\n\n<p>If you are building compatibility with such plugins, simply trigger <code>offload_image()<\/code> after the new image file is saved.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"example-\">Example:<\/h3>\n\n\n\n<div class=\"betterdocs-code-snippet-wrapper theme-light betterdocs-code-snippet-c98496f0\" id=\"betterdocs-code-snippet-c98496f0\" data-language=\"php\" data-copy-button=\"true\">\n\n            <div class=\"betterdocs-code-snippet-header betterdocs-file-preview-header\">\n        <div class=\"betterdocs-file-preview-left\">\n                            <div class=\"betterdocs-traffic-lights\">\n                    <span class=\"traffic-light traffic-light-red\"><\/span>\n                    <span class=\"traffic-light traffic-light-yellow\"><\/span>\n                    <span class=\"traffic-light traffic-light-green\"><\/span>\n                <\/div>\n            \n            <div class=\"betterdocs-file-info\">\n                                    <div class=\"betterdocs-file-icon\">\n                                                    <span class=\"betterdocs-file-icon-emoji\">&#128024;<\/span>\n                                            <\/div>\n                \n                                    <div class=\"betterdocs-file-name\">\n                        <span class=\"file-name-text\">filename.js<\/span>\n                    <\/div>\n                            <\/div>\n        <\/div>\n\n        <div class=\"betterdocs-file-preview-right\">\n                            <div class=\"betterdocs-code-snippet-copy-container\">\n                    <button class=\"betterdocs-code-snippet-copy-button\" type=\"button\" data-clipboard-target=\"#betterdocs-code-snippet-c98496f0 .betterdocs-code-snippet-code code\" aria-label=\"Copy code to clipboard\">\n                        <svg width=\"16\" height=\"16\" viewbox=\"0 0 24 24\" fill=\"none\" xmlns=\"http:\/\/www.w3.org\/2000\/svg\">\n                            <path d=\"M16 1H4C2.9 1 2 1.9 2 3V17H4V3H16V1ZM19 5H8C6.9 5 6 5.9 6 7V21C6 22.1 6.9 23 8 23H19C20.1 23 21 22.1 21 21V7C21 5.9 20.1 5 19 5ZM19 21H8V7H19V21Z\" fill=\"currentColor\"><\/path>\n                        <\/svg>\n                    <\/button>\n                                    <\/div>\n                    <\/div>\n        <\/div>\n    \n    <div class=\"betterdocs-code-snippet-content\">\n        \n        <pre class=\"betterdocs-code-snippet-code language-php\"><code>add_action( 'shortpixel\/image\/optimised', function( $image_path ) {\n    \/\/ Convert absolute path to a relative upload path\n    $upload_dir = wp_get_upload_dir();\n    $relative_path = str_replace( trailingslashit( $upload_dir['basedir'] ), '', $image_path );\n\n    offload_image( $relative_path );\n});\n<\/code><\/pre>\n    <\/div>\n<\/div>\n\n<script type=\"text\/javascript\">\ndocument.addEventListener('DOMContentLoaded', function() {\n    \/\/ Initialize copy functionality for this specific snippet\n    const snippet = document.getElementById('betterdocs-code-snippet-c98496f0');\n    if (snippet && window.BetterDocsCodeSnippet) {\n        window.BetterDocsCodeSnippet.initCopyButton(snippet);\n    }\n});\n<\/script>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"error-handling-debugging\">Error Handling &amp; Debugging<\/h2>\n\n\n\n<p>If you encounter issues:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Ensure the file physically exists in the uploads directory.<\/li>\n\n\n\n<li>Confirm that Infinite Uploads is connected and authenticated.<\/li>\n\n\n\n<li>Check your PHP error logs for messages generated during the offloading process.<\/li>\n\n\n\n<li>Verify that <code>$relative_path<\/code> is <strong>relative<\/strong>, not absolute.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"related-filters-and-hooks\">Related Filters and Hooks<\/h2>\n\n\n\n<p>When <code>offload_image()<\/code> runs, it aligns with the existing Infinite Uploads offload pipeline, allowing you to hook into:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><code>infinite_uploads_pre_offload_file<\/code><\/li>\n\n\n\n<li><code>infinite_uploads_post_offload_file<\/code><\/li>\n\n\n\n<li><code>infinite_uploads_offload_error<\/code><\/li>\n<\/ul>\n\n\n\n<p>(Names may vary depending on your implementation &mdash; update these if needed.)<\/p>\n<\/body><\/html>\n","protected":false},"excerpt":{"rendered":"<p>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&rsquo;s normal [&hellip;]<\/p>\n","protected":false},"author":3787,"featured_media":10760,"template":"","meta":{"_acf_changed":false,"wds_primary_doc_category":0,"wds_primary_doc_tag":0,"footnotes":""},"doc_category":[147],"doc_tag":[],"class_list":["post-10732","docs","type-docs","status-publish","has-post-thumbnail","hentry","doc_category-developers"],"acf":[],"year_month":"2026-04","word_count":395,"total_views":"314","reactions":{"happy":"0","normal":"0","sad":"0"},"author_info":{"name":"Blake Whittle","author_nicename":"blakew","author_url":"https:\/\/infiniteuploads.com\/blog\/author\/blakew\/"},"doc_category_info":[{"term_name":"Developers","term_url":"https:\/\/infiniteuploads.com\/docs-category\/developers\/"}],"doc_tag_info":[],"knowledge_base_info":[],"knowledge_base_slug":[],"_links":{"self":[{"href":"https:\/\/infiniteuploads.com\/api\/wp\/v2\/docs\/10732","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/infiniteuploads.com\/api\/wp\/v2\/docs"}],"about":[{"href":"https:\/\/infiniteuploads.com\/api\/wp\/v2\/types\/docs"}],"author":[{"embeddable":true,"href":"https:\/\/infiniteuploads.com\/api\/wp\/v2\/users\/3787"}],"version-history":[{"count":0,"href":"https:\/\/infiniteuploads.com\/api\/wp\/v2\/docs\/10732\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/infiniteuploads.com\/api\/wp\/v2\/media\/10760"}],"wp:attachment":[{"href":"https:\/\/infiniteuploads.com\/api\/wp\/v2\/media?parent=10732"}],"wp:term":[{"taxonomy":"doc_category","embeddable":true,"href":"https:\/\/infiniteuploads.com\/api\/wp\/v2\/doc_category?post=10732"},{"taxonomy":"doc_tag","embeddable":true,"href":"https:\/\/infiniteuploads.com\/api\/wp\/v2\/doc_tag?post=10732"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}