Skip to content

civi.afform.submit

Summary

This Symfony event is dispatched during Afform submission processing. It handles the saving of individual form entities in dependency order. Developers can use this event to customize records before they are saved, perform custom save logic, or intercept submission actions.

Definition

This event is dispatched via the Symfony EventDispatcher.

Core handles default entity persistence at priority 0 (Submit::processGenericEntity). To modify records before they are saved, register a listener with a higher priority (e.g. Events::W_EARLY or priority > 0). If performing custom save handling, call $event->stopPropagation() to prevent core's default handler from executing.

Adding a listener in <yourextension>_civicrm_config:

use Civi\API\Events;

function ehplay_civicrm_config(\CRM_Core_Config $config): void {
  Civi::dispatcher()->addListener('civi.afform.submit', ['Civi\Ehplay\HookHandler', 'onAfformSubmit'], Events::W_EARLY);
  _ehplay_civix_civicrm_config($config);
}
or adding a getSubscribedEvents method to your class:

use Civi\API\Events;

public static function getSubscribedEvents(): array {
   return [
     'civi.afform.submit' => [['onAfformSubmit', Events::W_EARLY]],
   ];
}

public static function onAfformSubmit(\Civi\Afform\Event\AfformSubmitEvent $event): void

Parameters

  • \Civi\Afform\Event\AfformSubmitEvent $event

Event Methods

  • getAfform(): array - Returns the main Afform configuration array.
  • getFormDataModel(): \Civi\Afform\FormDataModel - Returns the form data model instance.
  • getApiRequest(): \Civi\Api4\Action\Afform\Submit - Returns the active API request initiating the submit processor.
  • getRecords(): array - Returns the current array of records to be saved for this entity.
  • setRecords(array $records): self - Updates the array of records to be saved.
  • getSaved(): array - Returns details/results of saved records.
  • setSaved(int $index, array $savedValues): self - Sets the saved values for a record at the specified index (usually output of API4 save).
  • getSubmittedValues(): array - Returns all submitted entity and field values for the form.
  • getEntityType(): ?string - Returns the entity type of the current entity (e.g. Contact, Activity).
  • getEntityName(): string - Returns the name of the entity on the form (e.g. Individual1, Activity1).
  • getEntity(): array - Returns the form data model definition for the current entity.
  • getSecureApi4(): callable - Returns a secure, API4-style wrapper for executing APIv4 actions on behalf of the current entity.
  • getEntityId(int $index = 0): mixed - Returns the database ID of the entity at the given repetition index.
  • getEntityIds(?string $entityName = null): array - Returns all resolved database ID values for the given entity name.
  • setEntityId(int $index, int|string $entityId): self - Sets the database ID for the entity instance at the specified index.
  • setJoinIds(int $index, string $joinEntity, array $joinIds): self - Sets the join IDs for the entity instance at the specified index.
  • stopPropagation(): void - Stops event propagation to prevent subsequent handlers (such as core generic save) from running.

Availability

  • Available since CiviCRM 5.31
  • Methods getAfform(), getFormDataModel(), and getApiRequest() added in CiviCRM 5.36
  • Methods getRecords(), setRecords(), and getEntityId() added in CiviCRM 5.43
  • Methods getEntityType(), getEntityName(), getEntity(), getSecureApi4(), setEntityId(), and setJoinIds() added in CiviCRM 5.56
  • Method getEntityIds() added in CiviCRM 5.57
  • Methods getSaved(), setSaved(), and getSubmittedValues() added in CiviCRM 6.10

Example

use Civi\Afform\Event\AfformSubmitEvent;

public static function onAfformSubmit(AfformSubmitEvent $event): void {
  if ($event->getEntityName() === 'Individual1') {
    $records = $event->getRecords();
    foreach ($records as $index => &$record) {
      // Modify a field value before the record is saved by core
      $record['fields']['custom_field'] = 'preprocessed_value';
    }
    $event->setRecords($records);
  }
}