Reading order

Each hook is listed in the order it fires during a full form lifecycle. Within each hook:

• Type — filter (transforms value) vs action (side-effect only)
• Signature — callback signature, (int, int) priority/argcount where the framework registers with non-default
• Fires — what triggers it
• Return — expected shape if a filter; ignored if an action
• Use it when — what a sibling plugin would do here

Phase 1 — Plugin init / registration

These run when plugins load. They’re not in a single sequence — order depends on which plugin registers first.

Two parallel entry points, one per form source:

• Code-based (programmatic) forms → mam_form_manager_get_forms_from_plugins. Forms defined entirely in PHP. No Gravity Forms installation required. This is mam-main’s first-class native path
• Gravity-Forms-backed forms → mam_gf_get_form_settings. Forms built in the GF admin UI, bridged in by mam-gravity-forms-manager. Use when admins need to edit forms without code or when integrating with existing GF records

Pick whichever fits the use case; downstream phases (cache, fetch, prefill, submission) are identical for both.

mam_form_manager_get_forms_from_plugins

add_filter( 'mam_form_manager_get_forms_from_plugins', function ( $forms ) {
    $forms['my_internal_form'] = [
        'slug'   => 'my_internal_form',
        'fields' => [ /* ... */ ],
    ];
    return $forms;
} );

mam_gf_get_form_settings

mam_for_gravity_forms_form_result_form_<ID>

Phase 2 — Cache pre-warm

The framework hooks setup_forms_for_caching() onto mam_initial_phone_data. That triggers when the app first asks for phone data.

mam_initial_phone_data

Inside the framework’s handler (mam_for_gravity_forms_forms_manager::setup_forms_for_caching), per declared form:

form_id  = get_option( form_def.id )
if form_id > 0:
    build slug → field_id map from <form_def.id>_<slug> options
    form     = get_data_for_app(form_id)            ← fires Phase 3 hooks
    for each cached field:
        field = apply_filters( 'mam_form_manager_precached_field', field, form_id )
        if slug map has this field's id:
            field.populate_with_key = slug
    $local_app_form_array[] = form

mam_form_manager_precached_field

Phase 3 — Form fetch and shaping

local_app_gravity_forms::get_data_for_app( $form_id ) is the main shaper. It runs during pre-warm AND during cache-miss fetches. Hooks fire in the order below.

mam_gf_get_form

mam_gf_get_custom_form

mam_populate_gravity_form

mam_form_manager_content_class_<type>

mam_populate_gravity_form_final

mam_gf_populate_form_data_with_post_meta

mam_update_form_before_sending_<formid>

mam_update_form_before_sending

Phase 4 — Row → form lookup

Content classes call this when they’re publishing a row that references a form.

mam_gf_get_form_from_cache

$form_index = apply_filters( 'mam_gf_get_form_from_cache', 0, $form_id );
if ( $form_index ) {
    $row['form_id'] = (string) $form_index;
}

Phase 5 — Submission handling

When the app POSTs a submission, mam_gf_submit_app_form processes it. The form’s handler runs through a form-id-keyed filter.

mam_for_gravity_forms_form_result_form_<ID>

mam_gf_get_form_data

$values       = apply_filters( 'mam_gf_get_form_data', $fields, 'mam_aquaman_day_settings_' );
$booking_date = $values['booking_date']['value'] ?? '';

Note the trailing underscore — the framework expects it. Forgetting it makes every lookup miss.

mam_form_manager_send_notifications

mam_gravity_forms_after_form_processed

mam_for_gravity_forms_form_submitted_<ID>

The $local_app_form_array global

The cache. A simple indexed array of cached form arrays. Three rules:

1. Push, don’t insert — always append; don’t reorder. Existing rows reference forms by 1-based index
2. 1-based indexing on the wire — $local_app_form_array[0] is reachable via form_id: "1". get_form_from_cache returns (string) ( $index + 1 )
3. One copy per form_id — get_form_from_cache deduplicates by $form['formid']. Don’t push the same form_id twice

Forms in this array carry their fully-shaped payload, including choices, populate_with_key, and any custom keys you added via mam_populate_gravity_form. After phone-data assembly, this global is serialized into the mobile JSON’s form_data array.

Option-key conventions

The first two are the load-bearing convention. If populate_with_key isn’t appearing, walk through these options and verify each one has a value > 0.

Common firing-order gotchas

Submission handler isn’t firing

add_filter( 'mam_for_gravity_forms_form_result_form_' . get_option( 'foo' ), ... ) — when this line runs, get_option('foo') must already return the form ID. If your plugin loads before the option is set, the filter is registered with an empty form ID and never fires. Two fixes:

1. Set the option (via the admin UI) before deploying the plugin
2. Register late: hook your form-manager init onto init or plugins_loaded priority 20+, after the option is reliably set

populate_with_key is missing from the cached form

Three checks, in order:

1. Is <form_settings_id>_<slug> set to a positive GF field ID? If no, the framework can’t resolve the slug
2. Did the pre-warm run? mam_initial_phone_data must fire before anyone calls mam_gf_get_form_from_cache. If your content class is invoked from an earlier hook, the form gets loaded via the cache-miss path which skips populate-key stamping
3. Are you stamping populate_with_key yourself in mam_populate_gravity_form as belt-and-suspenders? Recommended for any new form

Choices keep getting overwritten

gform_pre_render and related GF web hooks do NOT fire for app-bound forms. If you set choices in those hooks they only apply on the web side. Move the logic to mam_populate_gravity_form.

Field arrives as object vs array

Some code paths hand you a GF_Field object; others hand you an array. Defensive code:

$fid = (int) ( is_object( $field ) ? ( $field->id ?? 0 ) : ( $field['id'] ?? 0 ) );

mam_form_manager_precached_field runs but my logic doesn’t

That hook only fires on the pre-warm pass. Cache misses skip it. Move to mam_populate_gravity_form.

See also

• End-to-end cookbook — worked example of all the above
• Prefill paths — row → form data flow
• Form submission lifecycle — post-handler details
• Form cache and invalidation — when the cache busts
• Per-form-id submission hook — deep dive on the result handler

Metadata