When I rebuilt the Portland Winter Light Festival set up, one of my main goals was to reduce the amount of repetitive data entry that had been occurring in regards to the website. With over 160 art pieces and performances, there was a lot of copy-paste-copy-paste going on that was soul crushing for the mostly volunteer run organization. Artists were filling out Google forms and then the WLF team was manually copying this over into the website. My solution for this was that to make the Accepted Artist Confirmation form do the heavy lifting, utilizing Gravity Forms Post Creation add-on. So now 80% of the information that is displayed on the website’s program is auto-populated. There’s been one area where this hasn’t been working, with mapping a multi-file upload to the experience image gallery.
This morning I got a concerning text message from the press director in which they bemoan this common pain point:
“One question for you regarding the number of images the artists can upload. Since the additional images need to be added manually by us, I’m considering proposing we don’t offer it. Only offer one photo per experience. It’s such a heavy lift for us. Misty will push back hard on this. I’m assuming there are no ‘quick’ fixes on the back end, that it must be done manually. Let’s discuss. I’d love to point to analytics to back me up, but I’m thinking we likely never recorded such info.”
This tutorial documents the solution for a common integration challenge: mapping a Gravity Forms Multi-File Upload field to an Advanced Custom Fields (ACF) Gallery field when using the Gravity Forms Advanced Post Creation Add-On.
1. The Initial Workflow: Expedition Goal
The goal is to expedite the process of creating “Experience” Custom Post Types (CPTs) for the Winter Light Festival website.
| Component | Purpose | Details |
| Form Plugin | Gravity Forms | Collects artist submissions via Form ID 12. |
| Post Creation | Gravity Forms Advanced Post Creation Add-On | Automatically creates a new “Experience” post upon form submission. |
| Field Type | Gravity Forms Multi-File Upload (ID 83) | Allows artists to upload multiple images for their art piece. |
| Post Field | ACF Gallery Field | Field named photo-gallery on the “Experience” CPT to hold all submitted images. |
2. The Problem: The Manual Workflow Trap
The initial attempt was to map the Gravity Forms Multi-File Upload field (ID 83) directly to the ACF Image Gallery Field (photo-gallery) within the Advanced Post Creation feed.
When a user submitted the form, the post was created, but the photo-gallery field remained empty. This forced editors to a manual and repetitive workflow:
- Open the newly created post.
- Manually upload or select the images from the Media Library.
- Add them one by one to the ACF Gallery field.
The automation failed because of a core data mismatch that neither the plugins nor the initial mapping could resolve alone.
3. The Technical Reason for Failure
The issue boiled down to two points of incompatibility:
- Data Format Mismatch: The ACF Gallery Field expects the data to be a PHP array of WordPress Attachment IDs (e.g.,
[101, 102, 103]). The Gravity Forms Add-On, when simply mapped as a custom field, often passes only the file URLs or a comma-separated string, which ACF rejects. - Attachment Status: Even if the files were uploaded to the Media Library, the Advanced Post Creation Add-On does not automatically set the
post_parentfor general media uploads. This means the images were “floating” in the Media Library, unattached to the new post ID, preventing advanced custom code (like usingget_attached_media) from finding them.
4. The Solution: Mapping and Custom Code
The solution required a two-step approach: modifying the feed mapping to handle the media uploads, and then adding custom code to perform the final ACF array formatting.
A. Modifying the Gravity Forms Feed Mapping
The files must be properly registered as attachments before the custom code runs.
- Navigate to Forms > Feeds and edit the Advanced Post Creation Feed.
- In the Post Content or Custom Fields tab, unmap the
photo-galleryfield. - Click the Media Library tab.
- In the Select Field dropdown, map your “Gallery Images” Multi-File Upload field (ID 83).
- Action: This forces the APC add-on to move the files out of the temporary Gravity Forms folder, create the Attachment IDs, and attach them to the new post.
B. The Custom PHP Code
The code hooks into the process after the post and attachments are created (gform_advancedpostcreation_post_after_creation) and handles the final step: gathering the IDs and saving them to the ACF Gallery field.
This script should be placed in your theme’s functions.php file, a custom functionality plugin, or a code snippets plugin:
// FORM ID: 12. Adds all images attached to the new post (via APC Media Library mapping)
// to the ACF Gallery field 'photo-gallery'.
add_action( 'gform_advancedpostcreation_post_after_creation_12', function ( $post_id ) {
// Check if the required ACF function is available.
if ( ! function_exists( 'update_field' ) ) {
gf_advancedpostcreation()->log_debug( __METHOD__ . '(): ACF update_field function not available.' );
return;
}
// 1. Get all images that the APC Add-On has attached to the new post ID.
$attached_images = get_attached_media( 'image', $post_id );
if ( ! empty( $attached_images ) && is_array( $attached_images ) ) {
// 2. Extract only the Attachment IDs (ACF input requirement).
$attached_image_ids = array_keys( $attached_images );
// 3. (Optional but recommended) Filter out the Featured Image ID if it was mapped separately.
$featured_image_id = get_post_thumbnail_id( $post_id );
$gallery_ids = $attached_image_ids;
if ( $featured_image_id ) {
// Remove the single Featured Image ID from the list if present.
$gallery_ids = array_diff( $attached_image_ids, array( $featured_image_id ) );
}
// 4. Use ACF's update_field function to save the array of IDs.
update_field( 'photo-gallery', $gallery_ids, $post_id );
gf_advancedpostcreation()->log_debug( __METHOD__ . '(): Successfully added IDs to ACF Gallery.' );
} else {
gf_advancedpostcreation()->log_debug( __METHOD__ . '(): No images attached by APC found for this post.' );
}
// The '4' here tells the hook to expect 4 arguments, satisfying the core hook execution.
}, 10, 4 );
This code was inspired by the solution that Gravity Forms provides at “Save to ACF Gallery field images attached to the post created“.
5. Testing and Debugging Checklist
The ability to successfully debug this process is key to maintenance.
A. How to Test
- Clear your browser and WordPress caches.
- Submit the Gravity Form with a multi-file upload.
- Go to the WordPress backend and check the newly created “Experience” CPT.
- Verify that the images appear automatically in the
photo-galleryACF field.
B. Debugging the Workflow
If the images do not appear, use the Gravity Forms Logging tool to verify the custom code execution:
- Enable Logging: Navigate to Forms > Settings > Logging.
- Select Advanced Post Creation Add-On and set the level to Error, Warning & Debug.
- Submit a test form.
- Check the Log: Return to the Logging tab and review the logs for the Advanced Post Creation Add-On.
Successful Log Entry (Goal):
You should see a message similar to:
Successfully added IDs to ACF Gallery: Array ( [0] => 101 [1] => 102 ... )
Failure Diagnosis:
If you see the message:
No images attached by APC found for this post.
This means Step 4A (Modifying the APC Feed Mapping) failed. The images are likely still stuck in the temporary Gravity Forms folder, and the APC add-on is not correctly handling them as Media Library items. Double-check that you correctly mapped the Multi-File Upload field in the Media Library tab of the APC feed.
6. Addendum: The Gravity Perks Alternative (GP Media Library)
While the custom PHP code solution works perfectly, a popular premium toolkit called Gravity Perks offers a no-code alternative that some developers or agencies may prefer.
What Gravity Perks Media Library Does
Gravity Perks (specifically the GP Media Library perk) provides an easier way to ensure your file uploads are correctly registered in the WordPress Media Library and attached to the new post before the Advanced Post Creation Add-On even runs its feeds.
- No Custom Code: It eliminates the need for the custom PHP snippet entirely.
- Early Registration: It handles the complex logic of moving files from the temporary Gravity Forms folder and creating attachment IDs during the form submission process.
- Simple Mapping: Once GP Media Library is enabled, you often just map the Multi-File Upload field to the ACF Gallery field in the standard APC mapping interface, and the perk ensures the correct array of IDs is passed.
They have an article “Uploading Files to Advanced Custom Fields Using the Gravity Forms Advanced Post Creation Add-On” and “How to Set a Featured Image and Add to ACF Gallery From The Same Field“.
Custom Solution vs. Plugin Solution
The decision to use your current custom code or invest in Gravity Perks comes down to priorities, budget, and development philosophy.
| Factor | Custom Code Solution (PHP Snippet) | Gravity Perks (GP Media Library) |
| Cost | Free. (Uses only core Gravity Forms and WordPress functionality). | Paid subscription. (Requires the Gravity Perks plugin bundle). |
| Maintenance | Requires a developer to maintain and troubleshoot the PHP snippet after major updates to Gravity Forms, ACF, or WordPress. | Maintenance is handled by the plugin developer (Gravity Wiz). Less developer effort required. |
| Ease of Setup | Requires comfortable working with code snippets and debugging via the Gravity Forms log. | No code required. Simple toggle switches in the form settings. |
| Scalability | Good for this one specific issue. If you face other GF/ACF issues, you’ll need more custom code. | Excellent. Gravity Perks solves many common Gravity Forms limitations with other add-ons (like conditional logic on payments, saving progress, etc.). |
| Debugging | Must rely on detailed log checks to ensure URLs resolve to IDs. | The plugin handles the core media process, simplifying the debugging of the APC feed itself. |
Reasons to use the Custom Solution:
- You have budget constraints or only need to solve this one specific issue.
- You are comfortable with PHP and maintaining your site’s code snippets.
- You want to avoid adding another third-party subscription dependency.
Reasons to use Gravity Perks:
- You manage multiple client sites where Gravity Forms is heavily used.
- You want a “set it and forget it” solution that is maintained by the vendor.
- You want to use other powerful features offered by the Gravity Perks suite, justifying the subscription cost.