{"id":10733,"date":"2025-12-01T16:31:40","date_gmt":"2025-12-01T22:31:40","guid":{"rendered":"https:\/\/infiniteuploads.com\/?post_type=docs&#038;p=10733"},"modified":"2025-12-01T16:37:36","modified_gmt":"2025-12-01T22:37:36","password":"","slug":"downloading-images-with-download_image-relative_path","status":"publish","type":"docs","link":"https:\/\/infiniteuploads.com\/docs\/developers\/downloading-images-with-download_image-relative_path\/","title":{"rendered":"Downloading Images with download_image( $relative_path )"},"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>You can trigger a remote image download from Infinite Uploads cloud storage using the new <code>download_image()<\/code> function. This is especially useful for integrations such as <strong>ShortPixel<\/strong>, on-demand image optimization, or any workflow that requires a file to exist locally before processing.<\/p>\n\n\n\n<p>This helper ensures the image is fetched from cloud storage, saved to the correct local uploads path, and returned for further processing.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"function-overview\">Function Overview<\/h2>\n\n\n\n<div class=\"betterdocs-code-snippet-wrapper theme-light betterdocs-code-snippet-1602d320\" id=\"betterdocs-code-snippet-1602d320\" 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-1602d320 .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>download_image( string $relative_path ): string|WP_Error\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-1602d320');\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\">Parameters<\/h3>\n\n\n\n<figure class=\"wp-block-table\"><table class=\"has-fixed-layout\"><thead><tr><th>Name<\/th><th>Type<\/th><th>Description<\/th><\/tr><\/thead><tbody><tr><td><code>$relative_path<\/code><\/td><td><code>string<\/code><\/td><td>The relative path (within the uploads directory) to the file you want to download. Example: <code>2025\/01\/my-image.jpg<\/code>.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"returns\">Returns<\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>String:<\/strong> The full local filesystem path to the downloaded file<\/li>\n\n\n\n<li><strong><code>WP_Error<\/code>:<\/strong> If the file could not be downloaded or written locally<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"example-use-case-integrating-with-shortpixel\">Example Use Case: Integrating with ShortPixel<\/h2>\n\n\n\n<p>ShortPixel requires local access to the file it is optimizing. When the asset is stored remotely in Infinite Uploads, it may not exist locally. Using <code>download_image()<\/code> ensures the file is present before triggering optimization.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"basic-example\">Basic Example<\/h3>\n\n\n\n<div class=\"betterdocs-code-snippet-wrapper theme-light betterdocs-code-snippet-176a5dcc\" id=\"betterdocs-code-snippet-176a5dcc\" 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-176a5dcc .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-photo.jpg';\n\n\/\/ Attempt to download from Infinite Uploads cloud storage.\n$local_file = download_image( $relative_path );\n\nif ( is_wp_error( $local_file ) ) {\n    error_log( 'Failed to download image: ' . $local_file-&gt;get_error_message() );\n    return;\n}\n\n\/\/ Hand the file off to ShortPixel or any other local processor.\nshortpixel_optimize_image( $local_file );\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-176a5dcc');\n    if (snippet && window.BetterDocsCodeSnippet) {\n        window.BetterDocsCodeSnippet.initCopyButton(snippet);\n    }\n});\n<\/script>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"how-it-works\">How It Works<\/h2>\n\n\n\n<p>When you call <code>download_image()<\/code>:<\/p>\n\n\n\n<ol class=\"wp-block-list\">\n<li>Infinite Uploads checks whether the file exists locally.<\/li>\n\n\n\n<li>If not available, it retrieves the remote object from Infinite Uploads cloud storage.<\/li>\n\n\n\n<li>The plugin writes the file to the correct location inside <code>\/wp-content\/uploads\/&hellip;<\/code>.<\/li>\n\n\n\n<li>The function returns the physical local path so you can work with the file normally.<\/li>\n<\/ol>\n\n\n\n<p>This gives developers a seamless way to interact with cloud-stored media as if it were local.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"common-uses\">Common Uses<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Image optimization pipelines (ShortPixel, EWWW, Imagify, etc.)<\/li>\n\n\n\n<li>Regenerating thumbnails<\/li>\n\n\n\n<li>Custom batch processors that rely on the local filesystem<\/li>\n\n\n\n<li>Migrating or syncing media libraries<\/li>\n\n\n\n<li>Any plugin that needs local access to a remote-stored file<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"error-handling\">Error Handling<\/h2>\n\n\n\n<p>Always check for errors:<\/p>\n\n\n\n<div class=\"betterdocs-code-snippet-wrapper theme-light betterdocs-code-snippet-12b2e344\" id=\"betterdocs-code-snippet-12b2e344\" 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-12b2e344 .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>$result = download_image( $relative_path );\n\nif ( is_wp_error( $result ) ) {\n    \/\/ Handle gracefully\n    wp_send_json_error( $result-&gt;get_error_message() );\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-12b2e344');\n    if (snippet && window.BetterDocsCodeSnippet) {\n        window.BetterDocsCodeSnippet.initCopyButton(snippet);\n    }\n});\n<\/script>\n\n\n\n<p>Typical error scenarios include:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>File not found in remote storage<\/li>\n\n\n\n<li>Insufficient write permissions on the server<\/li>\n\n\n\n<li>Connectivity issues during retrieval<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"notes-for-developers\">Notes for Developers<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li><code>$relative_path<\/code> must NOT begin with a slash. Use WordPress&rsquo; standard uploads-relative format.<\/li>\n\n\n\n<li>The function is designed to be lightweight; it only downloads the file if not already present.<\/li>\n\n\n\n<li>Works seamlessly with Infinite Uploads URL rewriting and file syncing.<\/li>\n<\/ul>\n<\/body><\/html>\n","protected":false},"excerpt":{"rendered":"<p>You can trigger a remote image download from Infinite Uploads cloud storage using the new download_image() function. This is especially useful for integrations such as ShortPixel, on-demand image optimization, or any workflow that requires a file to exist locally before processing. This helper ensures the image is fetched from cloud storage, saved to the correct [&hellip;]<\/p>\n","protected":false},"author":3787,"featured_media":10763,"template":"","meta":{"_acf_changed":false,"wds_primary_doc_category":0,"wds_primary_doc_tag":0,"footnotes":""},"doc_category":[147],"doc_tag":[],"class_list":["post-10733","docs","type-docs","status-publish","has-post-thumbnail","hentry","doc_category-developers"],"acf":[],"year_month":"2026-04","word_count":327,"total_views":"303","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\/10733","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\/10733\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/infiniteuploads.com\/api\/wp\/v2\/media\/10763"}],"wp:attachment":[{"href":"https:\/\/infiniteuploads.com\/api\/wp\/v2\/media?parent=10733"}],"wp:term":[{"taxonomy":"doc_category","embeddable":true,"href":"https:\/\/infiniteuploads.com\/api\/wp\/v2\/doc_category?post=10733"},{"taxonomy":"doc_tag","embeddable":true,"href":"https:\/\/infiniteuploads.com\/api\/wp\/v2\/doc_tag?post=10733"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}