It’s been a long wait but after many rounds of testing and refining, version 1.1.0 of the ACF Custom Database Tables plugin is stable and available to download for all current license holders via your Hookturn account page. For a summary of changes see what has changed in version 1.1.
I’m currently working through updates to our documentation and site content in preparation for the official release but I’m making the release candidate available so that anyone wishing to get started immediately can do so without having to wait. I also want to hear how the update performs for existing sites so if you can get updates and let me know via support@hookturn.io, that would be great.
Unless any bugs are found at this late stage, this will be the version release that we’ll start rolling out in the coming weeks.
Important things to note:
- This is a large update so you should test on a development/staging environment before deploying to your live site.
- This update will automatically rebuild the generated JSON and PHP files used to map data in/out of custom database tables.
- Repeater fields are not enabled by default — support needs to be enabled.
- There has been some changes to the underlying (non-API) code that are not backwards compatible. Make sure you test in a development/staging environment if you are calling on core plugin code.
Things to know before updating the plugin
The documentation is available for you to read here on Hookturn
The updated documentation is currently available right here.
The update affects files but not the database
In order to facilitate repeater fields in a way that is efficient, I’ve had to implement a few changes to the internal table map system that is generated when saving field groups and updating the database. To account for these changes, this update runs an upgrade which modifies all generated JSON and PHP files associated with the internal table map.
This update does not modify your database structure in any way.
The table map upgrade runs immediately after the plugin is updated (when a page in the WordPress admin is loaded) and should be done in less than a second for most sites. If a site has a large number of field groups, it might take a few seconds. The process runs in the background and an admin notice will appear either letting you know that it is running or it is complete. If there is some problem during this process, you can run the process manually. See this document for more details.
I’ve had to break semantic version practices for this release
Supporting the repeater field has required some significant changes under the hood and there have been some changes to classes and methods. Note that if you aren’t calling on code externally, this doesn’t affect you.
Note, all hooks/filters continue to function as documented in version 1.0.5.
Under semantic versioning, changes like this would typically warrant a major version increase but I’m choosing not to do that given we are locked in on version 1.1.0 for this release. The code that runs the plugin isn’t currently intended for use as an API of any sort but if you are calling on the plugin’s internals, be sure to test thoroughly before deploying the updated version to any live servers.
If you do run into trouble, please write in with a clear explanation of what you need to achieve & how you were previously achieving it so I can suggest potential alternative approaches for you. The more I can learn about your needs, the better I can plan out the PHP based API that I’ll be working on for a future release.
Test on a staging site first and be sure to back up your site before updating
I’ve spent a huge amount of time carefully working through the changes in a way that should impact few (if any) existing sites. This involves a lot of manual testing along with an extensive collection of automated tests (over 2000!) to prevent regression and inconsistencies between versions.
However, there are unexpected use cases and environmental discrepancies that may lead to bugs that are hard to foresee so please make sure you test this update in a development/staging environment before running it on your live sites. You should also back the site up before updating so you have something to roll back to. I suggest, at the very least, backing up your database and your ACF JSON directory as these will both be needed to roll back, should you need to.
Repeater field support needs to be enabled before they can be stored in custom tables
Repeater fields won’t immediately start to function after updating. I’ve chosen to make this opt-in to ensure people don’t get unintended side effects when updating a field group with an existing table.
To use repeaters, support needs to be enabled either via PHP code or via the plugin’s settings panel. See this document for more information.
The plugin now uses field keys as well as field names
Prior to version 1.1, the plugin used only field names to identify fields and map data to/from custom tables. This has worked fantastically well but due to the way repeater fields are processed and organised into core tables, I’ve had to add field keys into the mix to save on excessive use of looped RegEx matching.
This change minimises the performance overhead of handling repeater payloads but it does change the size and structure of the generated table maps files. I’ll be working on refining this even further as we add support for groups fields, flexible content fields, and some other goodies I’m still planning out.
How to update to the latest version
Updating is as simple as visiting the plugins page in the WordPress admin and using the plugin uploader to add the new version:
WordPress will prompt you if you are uploading a new version of an existing plugin which you can confirm. Updating this way will run the necessary background upgrades to the table map system so you should see a notification indicating the upgrade is running or done.
What to check for after update
After updating, it’s important to check the table map upgrade has resulted in an updated working table map. The table map ensures data is routed in/out of custom database tables so check for the following:
- Existing fields are displaying data correctly
- Newly created posts/users data is saved into custom tables
It’s also a good idea to double check the format of that data being saved on new posts is matching the format of existing data.
Getting started with repeater fields
There’s a four-step process in working with repeaters that you should be aware of:
- First, enable repeater support either via settings or via PHP (recommended)
- Implement any configuration filters if you wish to store a repeater’s values in a normalised table.
- Open field group with a repeater and save it to adjust the table JSON file.
- Run table create/update process to affect the database.
How to revert back to the previous version if necessary
If you need to revert back to the previous version, it’s simply a case of rolling the plugin files back to version 1.0.5 (which you can download from your Hookturn account page) and restoring your ACF JSON directory back to it’s previous state before updating.
If you don’t have a copy of the ACF JSON directory, you’ll need to resave all field groups with the reinstated plugin files in please in order to regenerate the JSON. Then, run the table create/update process to rebuild the map.
