Import folders from another plugin

Plathix can read the folder tree of five other media-folder plugins from the WordPress database and rebuild it as Plathix folders. Each file is put into the folder it had in the old plugin. Files stay where they are on the server, attachment IDs and URLs do not change, and the old plugin’s data is left as it is.

When you need this

• You move a blog with many authors from FileBird to Plathix and do not want to sort several hundred images again.
• An agency takes over a client site that used Real Media Library and wants the same folder plugin on all its sites.
• A WooCommerce store kept product photos in HappyFiles folders and changes plugins without changing any image URL.

How to check which plugins Plathix found

Plathix supports five source plugins. Their tiles appear on the card in this order:

No other plugins are supported.

1. Log in as an administrator. The Tools screen is for administrators only.
2. Go to Plathix → Tools.
3. Find the card Import from Other Plugins. Its text reads: “Migrate your folder structure from another plugin. Plathix will attempt to recreate the hierarchy and reassign all media attachments. This is non-destructive — original plugin data is preserved.”
   

4. Read the status on each tile.

Plathix looks for the plugin’s data, not for the plugin itself. A deactivated source plugin is still found while its folder data is in the database. A plugin that was deleted together with its data cannot be imported. A tile can show “✓ Detected” even when there are no real folders, for example when FileBird’s folder list is empty or when WP Media Folder has only its own root folder.

Plathix Home also shows a banner for the first detected plugin that has not been imported yet. It checks the plugins in the order FileBird, WP Media Folder, Real Media Library, HappyFiles, Wicked Folders. The banner is titled “{Plugin} detected” and reads: “We found an existing folder structure from {Plugin}. Import it to Plathix in one click — your organisation will be preserved.”

• Import from {Plugin} opens Plathix → Tools. There, click Import from {Plugin} on that plugin’s tile to start the import.
• Dismiss hides the banner for that plugin, for your user account only. The next detected plugin can then appear.

How to run the import

1. Back up the database. There is no undo button for a finished import.
2. Leave the source plugin installed. It can be active or deactivated.
3. Open Plathix → Tools.
4. On the tile of the source plugin, click Import from {Plugin}. There is no confirmation dialog and no preview.
5. Wait. The status line at the top of the card shows “Import queued. Waiting for Action Scheduler…” and then “Import is running…”. While it waits, the Import and Continue buttons are disabled.
6. Read the result: “Import completed. Moved items: N” (for one file: “Import completed. Moved item: 1”). Run each import once. Reload the Tools page to see the “✓ Imported” mark on the tile.
   

7. Open Media → Library. The imported folders are in the folder panel.

N is the number of times a file was put into a different folder. A file from several source folders can be counted more than once. Files that were already in the right folder are not counted.

The import runs in the background. The Tools screen follows the job for up to 2 minutes. Other messages on the status line:

• “Import is still pending. Action Scheduler runner may be unavailable.” The job did not finish within 2 minutes. It may still run later, or it may never have started. See Limits.
• “Could not check import status — connection is unstable. Please wait or try again later.” The page could not reach the site several times in a row. The job itself is not affected.
• “Import failed.” The background job failed, was canceled or could not be found.
• “Request failed.” The click got no usable answer, for example because the page’s security token expired. Reload the page and try again.
• “Import adapter is not available.” Plathix no longer finds the plugin’s data.
• “Import job already queued for this user.” and “Import queue is busy.” See Limits.

If the page’s security token expires, or your account loses access while the page waits, the check stops at once with “Import failed.” or “Insufficient permissions.”

What the import copies

• Folder names. Spaces at the ends are removed. Every run of whitespace, tabs and line breaks included, becomes one space. Names are cut to 200 characters.
• The folder tree with all its nesting levels. By default Plathix has no depth limit for folders.
• File-to-folder assignments. Each file goes into the folder it had in the source plugin.
• An order. Imported folders are placed after any folders that already exist at the same level, in the order the importer creates them. They are not sorted by name. Each per-plugin page gives that plugin’s read order.

The import does not copy:

• Folder colors.
• Settings of the source plugin, favorites, access rights and any other data that belongs to the source plugin.
• Folders for anything other than the Media Library. From the Tools screen the import always targets the Media Library.
• Plugin-specific extras, for example Real Media Library shortcuts or the WP Media Folder root container. See the per-plugin pages.

Files are not moved on the server. Attachment IDs and file URLs do not change. Only the Plathix folder a file is listed in changes.

How special cases are handled

• A folder with the same name already exists at the same level in Plathix. No new folder is created. The existing folder is reused and the files go into it. The exception is a same-name folder that is in Plathix Trash. Then a new folder is created. The folder in Trash gets a technical name, its folder ID plus __trashed (for example 57__trashed), and the Trash view shows that name until you restore it. Restore brings the original name back. If that name is taken by then, ” (2)”, ” (3)” and so on is added.
• A top-level source folder is named Uncategorized or Trash. Plathix uses these two names for its system folders. Rename source folders called Uncategorized or Trash in the source plugin before you import, for example to “Uncategorized (old)”.
• One file was in several folders in the source plugin. In Plathix a file is in one folder. Each assignment replaces the previous one, so the file ends up in the folder the importer handles last. Parents are handled before their subfolders, so a subfolder wins over its parent. Between unrelated folders, the one handled later wins. That is usually the one later in the plugin’s read order. A folder whose parent is listed after it waits for the next pass, and then wins over everything handled in the earlier pass.
• A file was already in a Plathix folder. The import moves it to the imported folder.
• A folder cannot be created. This happens when the name is empty, contains control characters other than whitespace, bidirectional or zero-width characters, or consists only of HTML markup. It also happens when the name is still over 200 bytes after it was cut to 200 characters. That is common with long Cyrillic, CJK or emoji names. The folder is skipped, and so is everything inside it. Files of skipped folders are not moved and are not counted.
• A file cannot be moved, for example because the attachment no longer exists. The file stays where it is.
• The source plugin has no folders. The import completes with 0 moved items, and the tile shows “✓ Imported” after a reload.

The reasons for skipped folders and files are not shown on screen. With WP_DEBUG on in wp-config.php, each reason goes to the PHP error log as a “[Plathix WARNING]” line with the message “Import: folder creation failed”. With the default settings these lines are not written.

How to continue or restart an interrupted import

Plathix saves a checkpoint after each pass over the folder list. Small trees usually finish in one pass, so a very early interruption may leave nothing to continue from. In that case click Import from {Plugin} again. The folders already created are reused by name.

When a checkpoint exists, the tile shows the notice “An unfinished import was detected. You can continue where it left off or start over.” with two buttons.

To continue:

1. Open Plathix → Tools.
2. On the tile with the notice, click Continue. Folders created before the interruption are not created again. A folder you deleted permanently in the meantime (Trash emptied) is created again. A folder that is still in Plathix Trash is not, and its subfolders that were not imported yet are skipped. The final “Moved items” count includes the files moved before the interruption.

To start over:

1. Open Plathix → Tools.
2. On the tile with the notice, click Start over. Plathix deletes the folders this import has created so far, then runs the import from the beginning.

Folders that existed in Plathix before the import are kept. Files are not moved back to where they were before the import. Files the import put into existing folders stay there. Files in the deleted folders are left without a folder.

Start over stays clickable while the page waits for a job. It can show two messages:

• “Import is already running for this adapter — cannot restart yet.” The interrupted job is still running.
• “Previous import cleanup did not fully complete — please try again shortly.” Some folders could not be deleted.

An unfinished checkpoint is kept for 72 hours. After that the notice disappears and the next click starts from the beginning. A daily background job deletes the folders that an expired unfinished import created. Folders that existed before the import are kept.

How to check the result and remove the old plugin

1. Open Media → Library and compare the Plathix folder tree with the tree in the source plugin.
2. Open a few nested folders and check that their files are there.
3. Check files that were in several folders in the source plugin. Each one is now in a single folder.
4. Reload Plathix → Tools. If at least one file was moved, the tile shows “✓ Imported” and its button is disabled.
5. When the result is right, deactivate the source plugin on the Plugins screen.
6. Delete the source plugin later if you no longer need it. Depending on that plugin’s settings, deleting it may remove its own folder data. The Plathix folders are not affected.

Plathix keeps the “✓ Imported” mark for each source plugin separately. The mark is set when at least one file was moved, or when the source had no folders at all. If the source had folders but no file was moved, the tile stays “✓ Detected”.

The import is a one-time copy, not a sync. Changes made in the source plugin after the import do not reach Plathix.

Example

Suppose a site used FileBird with the tree Editorial › Featured Images, Authors and Brand › Logos, Icons. summer-campaign.png is in Featured Images, office-interior.png in Authors and logo.png in Logos. In Plathix the site already has the top-level folders Videos and Infographics.

1. On Plathix → Tools, the FileBird tile would show “✓ Detected”.
2. You click Import from FileBird.
3. The status line would end with “Import completed. Moved items: 3”.
4. In Media → Library, with the default sort, the top level would read Videos, Infographics, Editorial, Brand. Editorial and Brand come after the existing folders, in the order FileBird lists them.
5. summer-campaign.png would be in Editorial › Featured Images, office-interior.png in Editorial › Authors and logo.png in Brand › Logos. Their URLs would not change.
6. After a reload of the Tools screen, the FileBird tile would show “✓ Imported”.

Limits

• Administrators only.
• One import per source plugin at a time. While an import from the same plugin is queued or running from your account, a new click shows “Import job already queued for this user.” or joins that same import. It does not start a second one.
• If other imports are already running on the site, you get “Import queue is busy.” Wait about a minute and try again.
• The import runs as a WordPress background task. It runs through WP-Cron and while someone uses wp-admin. If WP-Cron is turned off on your site, or your host blocks the site’s requests to itself, call wp-cron.php from a system cron job.
• Run each import once. Reload the Tools page to see the “✓ Imported” mark.
• The screen shows only the number of moved items. There is no per-folder report and no error list on screen.
• There is no “undo import” button. To remove imported folders, delete them by hand, or use Start from scratch on Plathix → Presets. It deletes all your Media Library folders, keeps the system folders, and asks first: “This will delete {N} Plathix folders. Media files will not be deleted. Continue?”
• PRO adds a command-line start: wp plathix import start --adapter=<key> with the keys happyfiles, filebird, realmedialib, wpmediafolder and wickedfolders, and wp plathix import available to list the sources. These commands need PRO, active with a valid license. Use the PRO version released for your Plathix version. See WP-CLI and PRO.

In short

Plathix Free imports folder trees from HappyFiles, FileBird, Real Media Library, WP Media Folder and Wicked Folders on Plathix → Tools. It copies folder names, nesting and file assignments, but not colors or the source plugin’s settings. Files stay on the server with the same IDs and URLs, and a file that was in several folders ends up in one. Back up first, run each import once, check the tree afterwards, and only then deactivate the old plugin. Reload the Tools screen after the import to see “✓ Imported”.