Production <-> Local ACF sync fix

[luukee]

Issue

The main issue is when merging feature branches into master the master /acf-json/ fields are overwritten or replaced by the incoming merge.

Preferred setup

Production site:

• only uses acf-json/ field groups
• no ACF data in DB
• wp-admin ACF not available

Local Devs

• sync all DB ACF with acf-json/ field groups
• yes ACF data in DB
• wp-admin ACF is available

Links for help:

• https://www.awesomeacf.com/how-to-avoid-conflicts-when-using-the-acf-local-json-feature/
• https://support.advancedcustomfields.com/forums/topic/git-deploy-workflow-for-acf-local-json-only-sync-on-production/
• https://dev.to/mandrasch/starting-to-work-with-acf-local-json-and-git-1d4m

[luukee]

ChatGPT Feedback

This article highlights a common issue with using ACF Local JSON in a collaborative environment, especially when ACF fields are directly edited on the production site. The core problem arises when the production database has newer ACF field modifications than the acf-json files, causing inconsistencies and ignoring JSON changes from version control.

To address this, the goal is to shift your workflow so that ACF fields are only managed via acf-json files stored in your version control, and the production site always loads fields exclusively from these JSON files. Below, I'll guide you through safely transitioning from your current setup to a more controlled environment where field groups are managed only through acf-json files.

Steps to Transition to ACF JSON Management

1. Backup Your Production Database

   • Before making any changes, back up your production database to ensure you have a safe restore point if anything goes wrong. Use a tool like WP Migrate DB Pro, UpdraftPlus, or your hosting provider's backup solution.

2. Export Existing ACF Field Groups from Production

   • Go to your production site’s ACF admin interface and export all field groups as JSON files (Tools > Export > ACF JSON). This ensures you capture the latest settings directly from the production database.

3. Replace Local acf-json Files with Production Exports

   • Copy the exported JSON files to your theme’s acf-json/ directory locally. This step ensures your local environment is now in sync with the production site’s ACF configuration.

4. Clear ACF Field Groups from the Production Database

   • To remove the ACF field groups from the production database:
     • In your local environment, use WP CLI or ACF tools to delete field groups from the database. Run this command locally to ensure ACF groups are only loaded from JSON:

       wp acf export --all --path=./wp-content/themes/your-theme/acf-json
       wp acf delete --all

     • Sync this change across your environments, including staging and production, by pushing your changes to your remote repository and deploying them.

5. Deploy the Clean Slate to Production

   • Deploy your updated theme with the acf-json files to the production site. This step sets the groundwork for the production site to rely on JSON files only.

6. Force Production to Load ACF Field Groups from JSON Only

   • Modify your theme’s functions.php to ensure ACF only loads from JSON files and not from the database. Here’s a code snippet to enforce this:

     add_filter('acf/settings/load_json', function ($paths) {
         // Remove original path (optional but recommended)
         unset($paths[0]);
     
         // Append our JSON path
         $paths[] = get_stylesheet_directory() . '/acf-json';
         return $paths;
     });
     
     add_action('admin_menu', function () {
         // Hide ACF admin on production to prevent accidental edits
         if (!current_user_can('manage_options')) {
             remove_menu_page('edit.php?post_type=acf-field-group');
         }
     });

   • This code ensures your production site loads ACF field groups only from your theme’s acf-json directory and hides the ACF menu to prevent accidental changes.

7. Test the Production Site

   • Once deployed, visit the production site and ensure that all ACF field groups are functioning correctly. Test the fields in your templates to verify everything loads as expected.

8. Establish a New Workflow for ACF Field Group Changes

   • Make it a standard practice for all developers to:
     • Pull the latest changes from the repository.
     • Sync the ACF JSON files to their local database via the ACF admin interface.
     • Make changes locally, save the field group, and commit the updated JSON files.
   • Changes to ACF fields should always be deployed through Git, not directly on the production site.

9. Communicate the Workflow Changes with Your Team

   • Educate your team on the new process. Make it clear that ACF field group changes should only occur locally and be synced using the version-controlled JSON files.

Conclusion

By following these steps, you can successfully transition from managing ACF fields directly on the production database to a controlled environment where ACF field groups are managed exclusively through JSON files in version control. This approach minimizes conflicts, maintains consistency across environments, and aligns your workflow with best practices for collaborative development with ACF.