Documentation Custom Field Migrator & Cleaner

Documentation for the Custom Field Migrator & Cleaner plugin

About the plugin

Custom Field Migrator & Cleaner is a craftsman’s tool

  • This plugin is a tool—just like a craftsman’s tool. It lets you convert custom fields at a deep level, change labels, clean up custom fields, and more.
  • That means that, as a craftsman, you sometimes have to play around with the settings (especially the migration rules) to achieve the desired result.
  • Always make a copy of the database first (especially with cleaning and renaming fields) so that if you make a mistake, you can restore it.

How the plugin works

  • Migrate content from one custom field to another custom field.
  • Migrate content from one custom field type to another custom field type, like text to textarea or text to WYSIWYG or rich-text.
  • Migrate content from a custom fields plugin, like ACF or Metabox, to custom fields created with any other plugin, like ACPT, Modern fields, etc.
  • Temporary compatibility mode to ensure your templates that ask for the values in the old fields are getting them from the new fields.
  • Change the visible name (the label) of any custom field.
  • Tracking and removing old or unused custom fields, including _subfields.
  • Use the Custom Post assist to migrate your custom posts and taxonomies.
  • Works with: ACF, SCF, ACPT, MetaBox, JetEngine, Toolset and Modern fields.
  • Adds a new block to your website: Meta field (text — migrator). It shows the content of every custom field, but without rendering: it shows the pure content of the custom fields saved in the WordPress database as readable text.

What each tab is for

Field migration

  • Map the source meta keys to the target keys.
  • Choose field types and syntax.
  • Convert in batches.

Temporary compatibility

  • While templates still call old keys, this proxy functionality reads the new keys.
  • This allows you the necessary time to change the templates while the site keeps working.
  • When all the blocks in your template / elements are set to the new meta keys, you can remove the old keys and disable the temporary compatibility,

Clean old keys

  • Permanently delete leftover post meta rows you no longer need (license required).
  • Most actions in the Custom Field Migrator & Cleaner are non-destructive; this action is not.
  • Make a backup of your database first.

Change key label

  • Rename the admin label in a field plugin’s definitions (meta keys stay the same; license required).

Posttype assist

  • Checklist for recreating a custom post type with the same slug in another plugin.

License

  • Activate your Payhip / WPinsight license key on this site.
  • Enter the license key from your Payhip purchase. The key is validated and activated on this site via WPinsight.
  • Always deactivate a license on an unused website; otherwise your activation slot remains occupied.

Meta field block

  • Custom Field Migrator & Cleaner adds a new block to your site: Meta field (text — migrator).
  • This block shows the content of every custom field, but without rendering: it shows the pure content of the custom field as saved in the WordPress database. Use it to check the content and make a founded decision with the migration settings.

Free vs licensed

  • Free: 1 mapping row.
  • Activate a license for Unlimited rows, Clean old keys, and Change key label.
  1. Backup the database (and ideally work on a staging copy first).
  2. Create the destination fields in the target field plugin (same post types). This tool does not create field definitions for you.
  3. Set Translation context (Source and Target plugins) so syntax defaults match how each plugin stores values.
  4. Add mapping rows. Use View on a Source key to inspect a real stored sample before choosing Target type and syntax.
  5. Convert a small set first (one post type, few rows ticked). Check results in the editor and with the Meta field (text — migrator) block if needed.
  6. When satisfied, convert the rest. Optionally enable Temporary compatibility while you update templates.
  7. After templates use the new keys, disable compatibility and Clean old keys if you want to remove legacy meta.

Good to know

Create the new custom fields first

  • The Custom Field Migrator & Cleaner is a tool to migrate from one field to another, including fields from one custom fields plugin to fields from another custom fields plugin. It doesn’t create those fields for you.
  • First mirror the old fields within the new custom field plugin; with the same values but preferably small variations in the name, for example main_image to main__image or main_imagenew, So that you clearly see the distinction between the old and the new fields.

Convert image from ID to URL

  • What happens when the original custom fields holds an image value as an ID, but you require a URL?
  • When you need to convert an image ID into an image URL, our plugin automatically fetches the original image’s URL and utilizes it for the new custom image field. There’s no special setup required; the process happens seamlessly.

ACF and ACPT are not fully compatible

  • ACF and ACPT are not fully compatible when both are active on the same post type.
  • Edit ACF source fields (especially images) while ACPT is deactivated, then reactivate ACPT and run Convert.
  • An empty small thumbnail in the ACPT post editor is usually an ACPT + ACF coexistence issue, not failed migration — frontend and postmeta can still be correct.
  • Deactivate ACPT temporarily → edit ACF source fields if needed → Save posts → reactivate ACPT → run Convert.
  • Source and target keys stay separate (e.g. acf-author-image vs acpt-books_acpt-author-image).
  • Convert copies from source to target only when you run it.

Cheap hosting and cache

  • Some affordable hosting uses strong internal caching even without a cache plugin.
  • Old custom field values can appear in the editor or on the front end long after migration succeeded. That does not mean Convert failed — wait, hard-refresh, or ask your host how to flush object/page cache for that post(s).

What happens when you deactivate the plugin

  • Unless you are using the Temporary Compatibility feature, there is no further action required. If you have successfully completed the migration, cleaned up the old database fields, and adjusted your templates, it is perfectly fine to disable the plugin. It serves as a handy tool during the transition, but once your work is done, it is no longer necessary.

Tips

  • Source meta is never deleted by convert—only copied/transformed into the targetkeys.
  • Repeaters, flexible content, and other nested structures are not supported for automatic conversion.
  • If a conversion looks wrong, adjust the source/targetsyntax (or field type) and try again on staging before a full run.
  • If you found a good setting for a set of custom fields, make a screenshot and keep it save.
  • Custom post types (not custom fields) must keep the same slug when you switch registration plugins, or existing posts will not line up.