Creates or updates a contact from an associative array of field values and an optional field map. The field map connects source field keys to Groundhogg contact fields — for example 'email', 'first_name', 'last_name', or any meta key. Use the special destination value 'full_name' to have Groundhogg split a combined name automatically. If no map is provided, field keys are used directly as Groundhogg field keys. This is the recommended way to create contacts from custom form integrations.
Parameters
| Parameter | Type | Description |
|---|---|---|
$fields | array | Associative array of raw field data from the source (e.g. a form submission). |
$map | array | Associative array mapping source field keys to Groundhogg field keys. If empty, source keys are used directly. |
$submission | array | Optional submission-level settings such as tags to apply or notes to add. |
$contact | Contact|null | An existing contact to update instead of creating a new one. Default null (create new). |
Return value
Contact|false — The created or updated Contact object, or false on failure.
Usage
$fields = [
'your_email' => 'jane@example.com',
'your_name' => 'Jane Smith',
];
$map = [
'your_email' => 'email',
'your_name' => 'full_name',
];
$contact = \Groundhogg\generate_contact_with_map( $fields, $map );
Example
Here’s a pseudo code example for a hypothetical third-party form integration.
add_action( 'my_form_plugin_submission', 'my_plugin_handle_form_submission' );
/**
* Create a contact from a third-party form submission.
*
* @param array $submission Raw field data from the form.
*
* @return void
*/
function my_plugin_handle_form_submission( $submission ) {
$map = [
'email' => 'email',
'full_name' => 'full_name',
'phone_number' => 'phone_number',
'company' => 'company_name',
];
$contact = \Groundhogg\generate_contact_with_map( $submission, $map );
if ( ! $contact ) {
return;
}
\Groundhogg\after_form_submit_handler( $contact );
}
Was this helpful?
Let us know if this document answered your question. That’s the only way we can improve.