Rebuilding the map system

The map system is an essential aspect of the ACF Custom Database Tables plugin as it determines which table and column a field's data should be stored in and retrieved from. Without the table map, the plugin is unable to correctly route field data in/out of custom database tables.

What is the map system?

The map system consists of a numher of .json files as well as a .php file. If a site has ACF JSON enabled, the files will all be stored within the acf-json directory under acf-json/database-tables. If ACF JSON is not enabled, the files will be stored in wp-content/uploads/acf-custom-database-tables.

Directly inside the map directory there will be any number of .json files, each containing a JSON object that defines the schema of one or more database tables.

Also within the map directory is a .cache directory and within that, a file called .cache/_table_map.php. The PHP file contains a PHP multi-dimensional array that defines the complete custom table map and is generated by the plugin when it parses all of the .json files within the map directory.

When is the map system normally updated?

The .json files are created/updated when a field group is saved. Changes to the .json files have no immediate effect on data routing and do not alter the database in any way.

When the table creation/update process is run in Custom Fields > Database Tables > Manage Tables, the cached _table_map.php file is regenerated. The database is also modified during this process.

Why would the map system need to be regenerated?

As new field supports are added to the plugin, there may be the need to regenerate the map system using alternative structures. Changes to this system are only implemented when necessary and will often be driven by the need to keep the map system efficient while supporting complex field structures.

What happens when the map system rebuild tool is run?

When the map system rebuild tool is run, the plugin looks for all field groups that have a table JSON file on disk. Once it determines which field groups to affect, it rebuilds the table JSON file for each file and then finaly rebuilds the .cache/_table_map.php file.

The rebuild tool does not make any changes to the database in any way.

Does this modify the database?

No, the database isn't touched at all during a table map update — only the JSON files and a generated PHP file are regenerated.

Why is there only a small set of field groups available for rebuild?

Only field groups that are currently included in the map are available for rebuild. The systems looks up all available field groups and filters the list down to all field groups that meet the following criteria:

1. Has a table definition JSON file defined in its settings.
2. Has a table definition JSON file of the same name within the acf-json/database-tables or uploads/acf-custom-database-tables directory.

If a field group meets both criteria, it is available for rebuild.

Will this work for JSON-based field groups?

Yes, it will work with JSON-based field groups, even if they don't have a field group post in the database. This ensures sites that are loading fields from JSON only are supported and facilitates workflows where field configurations are deployed by pushing JSON files only.

What if the update process fails or if I notice fields aren't loading from or storing to custom tables?

If you are noticing any issues here, the best thing to do would be to manually enforce the updated schema as follows:

1. Determine which field groups with custom database tables are having the issue.
2. Navigate to the field group edit screen in Custom Fields > Field Groups > .
3. Save the field group to affect its table definition JSON file.
4. Run the table update process via the prompt that appears in order to update the PHP map file.

If you have muliple field groups to update, you can save all of them before running the table update process.

If you don't have the field groups in the admin, you'll need to sync the local JSON files.