Skip to content

Backgrounds

How-to Guides

Technical References

Import media files

The VIP platform offers a self-service tool for importing media into the VIP File System, making it easier to migrate from an existing WordPress site to one hosted with VIP.

Limitations

  • Media can only be imported to a production environment. Importing media to non-production environments is not necessary, as media uploaded to production is immediately made available to the child environments as well.
  • Only one import per environment is currently allowed. Attempts to start a second import while a previous import is still in progress will result in an error.
  • The size of the entire archive that holds the files to be imported cannot be more than 30 GB.
  • After a file has been imported, it cannot be deleted from the File System.
  • Google Drive URLs are not supported at this time. When using Dropbox, make sure that the URLs are downloadable directly.

Directory structure

The directory to be imported must be named /uploads/. In most cases, media uploaded to a WordPress install is stored in a directory /uploads/, which is a subdirectory of /wp-content/. To prepare media files for import to VIP, an archived copy of the /uploads/ directory is required. If you do not place the /uploads/ folder at the root of the archive, the import tool will import the archive to the /uploads/ directory by default, using whatever folder structures is present.

If a non-VIP WordPress site has customized the name of the /uploads/ directory, an extra step will be needed to duplicate the directory to a working location and re-name the duplicate directory to /uploads/ before the media can be imported to VIP.

If there is no /uploads/ directory found in the archive’s directory structure, all files will be imported with their existing structure.

Multisites

Media import directories for multisites must also be named /uploads/. However the sub-directory structure of the /uploads/ directory for sites belonging to a WordPress multisite will differ from WordPress single sites. The /uploads/ file path for the root site (Site ID 1) of the multisite will be /uploads/, but all subsequent sites on your network will be in the /uploads/sites/ directory structure, in their own subfolder based on the site number, designated by the database.

Upload paths for non-root sites follow the pattern /uploads/sites/{SITE ID}/{YYYY}/{MM}/{FILE NAME}, and values for {SITE ID} do not have any leading 0’s (e.g., use 2, not 02).

Import media files with VIP-CLI

Prior to running any import commands, confirm all items in this checklist:

  1. A current version of VIP-CLI is installed.
  2. Import files are archived (.tar.gz, .tgz, .tar.bz2, or .zip).
  3. The archive decompresses to a directory named /uploads/ , and only contains the media required for your site(s).
  4. Import files are uploaded to a publicly accessible URL (e.g., https://www.example.com/uploads.tar.gz). File-sharing services such as Dropbox, Box, or WeTransfer can also provide a public URL like this, if needed. Google Drive links do not work. If it’s a Dropbox link, make sure it’s downloadable, typically with a URL ending in ?dl=1.

Note

Specify the app and its environment that are the destination for the import by providing the app alias, a dot separator, and the environment name, in the form of:
@<app-alias or app ID>.<env>.

The @mysite.production values in the command examples below are for demonstration only.

VIP-CLI commands for media import

Initiate the import of the contents of the archive to a production environment:

vip import media @mysite.production "https://www.example.com/uploads.tar.gz"

Add the --overwriteExisting option (or -o ) to force the silent overwrite of existing files during import:

vip import media @mysite.production "https://www.example.com/uploads.tar.gz" --overwriteExisting

During the import process, the CLI will display the real-time progress of the import. If desired, the real-time progress of an import can be hidden using the Ctrl + C key combination.

When all files in the archive have been processed, it will return with a status report saved in the current working directory. The exact path to this status report will be shown on screen.

Check on the status of an import

A text status report on progress can be requested during the import:

vip import media status @mysite.production

A status report in JSON format can also be obtained by adding the option --exportFileErrorsToJson (or -E) to the command above.

Abort an ongoing Import

The import process can be aborted after the process has begun. Any files imported up until the abort command was executed cannot be deleted.

vip import media abort @mysite.production

Additional commands and options

Refer to the help menu for additional options, commands, and examples:

vip import media --help

Special characters in filenames

WordPress Core sanitizes file names, removing or replacing special characters upon upload to the media library, for example:
 ~?,[]/\=<>:;'\&$#*()|~`!{}%+ and whitespace ().

Media file imports to VIP bypass the WordPress sanitize_file_name() function, and all special characters are allowed, for example:
spaces ( ) [ ] ~ + & # % = ' ” \ < > : ; , / ? $ * | ` ! { } .
Encoded or alternate whitespace, such as %20or + will be converted to proper spaces during the import.

Intermediate images

Traditional installations of WordPress create intermediate images, an array of smaller versions of each uploaded image. The generated intermediate files are unnecessary on VIP, as the VIP File System is able to generate and cache any requested dimension of the originally uploaded image. This reduces the amount of storage a site requires and provides image size flexibility at no loss of speed. It is recommended that intermediate images are excluded from the imported media directory.

Intermediate images can be imported using the -i flag on the command. Including intermediate images in an import will cause the process to take a longer time to complete.

Unsupported file types

Imports to the VIP File System will fail for the following file types:

  • Files without extensions
  • Files not included in the list of file types supported by the VIP File System
  • Hidden files or or files within hidden directories will be ignored. Hidden files will not be included in the count of files that are discovered by the import media command, and they will not be included in the final count of files that are successfully imported.

WebPs

Though WordPress v5.8 adds *.webp file types to WordPress Core’s list of mime types and file extensions, this file type cannot be imported to VIP’s File System.

The VIP Platform automatically converts and serves all images as next-gen formats, including *.webp files, to compatible browsers. As a result, there is no need to upload *.webp files or directly reference them in your theme. Any unique *.webp files should be converted to JPG or PNG before import, and all references to *.webp files in the content should be changed prior to database import.

If a media import contains files with the *.webp file extension, or files with alternative extensions but webp mime type, those files will not work with the File System as expected.

SVGs

SVG files allow embedded JavaScript, which can pose a security risk. If SVGs exist in the /uploads/ directory that will be imported, it is recommended to scan the file contents prior to media import. The file contents of an SVG can be scanned by:

All SVG files committed to a GitHub repository by all customers will undergo a PHPCS scan using the WordPress-VIP-Go standard from the VIP code analysis bot and any discovered irregularities will be reported in the automated code review.

Last updated: July 15, 2021