Events#

Formie provides a multitude of events for extending its functionality. Modules and plugins can register event listeners, typically in their init() methods, to modify Formie’s behavior.

Form Events#

The `beforeSaveForm` event#

The event that is triggered before a form is saved. You can set $event->isValid to false to prevent saving.

use craft\events\ModelEvent;
use verbb\formie\elements\Form;
use yii\base\Event;

Event::on(Form::class, Form::EVENT_BEFORE_SAVE, function(ModelEvent $event) {
    $form = $event->sender;

    $event->isValid = false;
});

The `afterSaveForm` event#

The event that is triggered after a form is saved.

use craft\events\ModelEvent;
use verbb\formie\elements\Form;
use yii\base\Event;

Event::on(Form::class, Form::EVENT_AFTER_SAVE, function(ModelEvent $event) {
    $form = $event->sender;
});

The `beforeDeleteForm` event#

The event that is triggered before a form is deleted.

The isValid event property can be set to false to prevent the deletion from proceeding.

use verbb\formie\elements\Form;
use yii\base\Event;

Event::on(Form::class, Form::EVENT_BEFORE_DELETE, function(Event $event) {
    $form = $event->sender;
    $event->isValid = false;
});

The `afterDeleteForm` event#

The event that is triggered after a form is deleted.

use verbb\formie\elements\Form;
use yii\base\Event;

Event::on(Form::class, Form::EVENT_AFTER_DELETE, function(Event $event) {
    $form = $event->sender;
});

Form Render Events#

The `modifyRenderForm` event#

The event that is triggered when a form is rendered using the craft.formie.renderForm() function.

use verbb\formie\events\ModifyRenderEvent;
use verbb\formie\services\Rendering;
use yii\base\Event;

Event::on(Rendering::class, Rendering::EVENT_MODIFY_RENDER_FORM, function(ModifyRenderEvent $event) {
    $html = $event->html;
    // ...
});

The `modifyRenderPage` event#

The event that is triggered when a form page is rendered using the craft.formie.renderPage() function.

use verbb\formie\events\ModifyRenderEvent;
use verbb\formie\services\Rendering;
use yii\base\Event;

Event::on(Rendering::class, Rendering::EVENT_MODIFY_RENDER_PAGE, function(ModifyRenderEvent $event) {
    $html = $event->html;
    // ...
});

The `modifyRenderField` event#

The event that is triggered when a form field is rendered using the craft.formie.renderField() function.

use verbb\formie\events\ModifyRenderEvent;
use verbb\formie\services\Rendering;
use yii\base\Event;

Event::on(Rendering::class, Rendering::EVENT_MODIFY_RENDER_FIELD, function(ModifyRenderEvent $event) {
    $html = $event->html;
    // ...
});

Submission Events#

The `defineSubmissionRules` event#

The event that is triggered to modify or define additional validation rules for submissions.

use verbb\formie\elements\Submission;
use verbb\formie\events\SubmissionRulesEvent;
use yii\base\Event;

Event::on(Submission::class, Submission::EVENT_DEFINE_RULES, function(SubmissionRulesEvent $event) {
    $submission = $event->submission;
    $rules = $event->rules;
    // ...

    // Add a required field for field with handle `emailAddress`
    $event->rules[] = [['field:emailAddress'], 'required'];
});

The `beforeSaveSubmission` event#

The event that is triggered before a submission is saved. For multi-page forms, this event will occur on each page submission, as the submission is saved in its incomplete state.

You can set $event->isValid to false to prevent saving.

use craft\events\ModelEvent;
use verbb\formie\elements\Submission;
use yii\base\Event;

Event::on(Submission::class, Submission::EVENT_BEFORE_SAVE, function(ModelEvent $event) {
    $submission = $event->sender;

    $event->isValid = false;
});

The `afterSaveSubmission` event#

The event that is triggered after a submission is saved. For multi-page forms, this event will occur on each page submission, as the submission is saved in its incomplete state.

Do note the difference between this event and afterSubmission.

use craft\events\ModelEvent;
use verbb\formie\elements\Submission;
use yii\base\Event;

Event::on(Submission::class, Submission::EVENT_AFTER_SAVE, function(ModelEvent $event) {
    $submission = $event->sender;
});

The `beforeSubmission` event#

The event that is triggered before a submission has been completed. For multi-page forms, this is triggered when the final page has been reached and is being submitted.

use verbb\formie\events\SubmissionEvent;
use verbb\formie\services\Submissions;
use yii\base\Event;

Event::on(Submissions::class, Submissions::EVENT_BEFORE_SUBMISSION, function(SubmissionEvent $event) {
    $submission = $event->submission;
    // ...
});

The `beforeIncompleteSubmission` event#

The event that is triggered before a submission has been made, but is incomplete. This is primarily for multi-page forms, where this event is fired on each submission of each page, except the final page.

use verbb\formie\events\SubmissionEvent;
use verbb\formie\services\Submissions;
use yii\base\Event;

Event::on(Submissions::class, Submissions::EVENT_BEFORE_INCOMPLETE_SUBMISSION, function(SubmissionEvent $event) {
    $submission = $event->submission;
    // ...
});

The `afterSubmission` event#

The event that is triggered after a submission has been completed, whether successful or not. For multi-page forms, this is triggered when the final page has been reached and submitted.

You should always check $event->success if you want to ensure your event only triggers on submissions that have been successful.

use verbb\formie\events\SubmissionEvent;
use verbb\formie\services\Submissions;
use yii\base\Event;

Event::on(Submissions::class, Submissions::EVENT_AFTER_SUBMISSION, function(SubmissionEvent $event) {
    $submission = $event->submission;
    $success = $event->success;
    // ...
});

The `afterIncompleteSubmission` event#

The event that is triggered after a submission has been made, whether successful or not, not while the submission is incomplete. This is primarily for multi-page forms, where this event is fired on each submission of each page, except the final page.

You should always check $event->success if you want to ensure your event only triggers on submissions that have been successful.

use verbb\formie\events\SubmissionEvent;
use verbb\formie\services\Submissions;
use yii\base\Event;

Event::on(Submissions::class, Submissions::EVENT_AFTER_INCOMPLETE_SUBMISSION, function(SubmissionEvent $event) {
    $submission = $event->submission;
    $success = $event->success;
    // ...
});

The `beforeDeleteSubmission` event#

The event that is triggered before a submission is deleted.

The isValid event property can be set to false to prevent the deletion from proceeding.

use verbb\formie\elements\Submission;
use yii\base\Event;

Event::on(Submission::class, Submission::EVENT_BEFORE_DELETE, function(Event $event) {
    $submission = $event->sender;
    $event->isValid = false;
});

The `afterDeleteSubmission` event#

The event that is triggered after a submission is deleted.

use verbb\formie\elements\Submission;
use yii\base\Event;

Event::on(Submission::class, Submission::EVENT_AFTER_DELETE, function(Event $event) {
    $submission = $event->sender;
});

The `beforeSendNotification` event#

The event that is triggered before an email notification is sent.

The isValid event property can be set to false to prevent the notification from proceeding.

use verbb\formie\events\SendNotificationEvent;
use verbb\formie\services\Submissions;
use yii\base\Event;

Event::on(Submissions::class, Submissions::EVENT_BEFORE_SEND_NOTIFICATION, function(SendNotificationEvent $event) {
    $submissionId = $event->submissionId;
    $notificationId = $event->notificationId;
    // ...
});

The `beforeTriggerIntegration` event#

The event that is triggered before an integration is triggered.

The isValid event property can be set to false to prevent the integration from proceeding.

use verbb\formie\events\SendNotificationEvent;
use verbb\formie\services\Submissions;
use yii\base\Event;

Event::on(Submissions::class, Submissions::EVENT_BEFORE_TRIGGER_INTEGRATION, function(SendNotificationEvent $event) {
    $submissionId = $event->submissionId;
    $integration = $event->integration;
    // ...
});

The `beforeSubmissionRequest` event#

The event that is triggered before a submission is validated. This is triggered on the controller action endpoint, so should primarily be used for modification of the submission before validation, or any other use-case that needs to occur in the controller.

The isValid event property can be set to false to prevent the submission from being validated, and instead stop on your own validation notices.

use verbb\formie\controllers\SubmissionsController;
use verbb\formie\events\SubmissionEvent;
use yii\base\Event;

Event::on(SubmissionsController::class, SubmissionsController::EVENT_BEFORE_SUBMISSION_REQUEST, function(SubmissionEvent $event) {
    $submission = $event->submission;
    $success = $event->success;
    // ...

    // Add an error for a field
    $event->submission->addError('emailAddress', 'This did not validate');

    // Tell Formie that the submission is now invalid, and to raise errors
    $event->isValid = false;
});

The `afterSubmissionRequest` event#

The event that is triggered after a submission has been completed, whether successful or not. This is triggered on the controller action endpoint, so should primarily be used for redirection hijacking, or any other use-case that needs to occur in the controller.

use verbb\formie\controllers\SubmissionsController;
use verbb\formie\events\SubmissionEvent;
use yii\base\Event;

Event::on(SubmissionsController::class, SubmissionsController::EVENT_AFTER_SUBMISSION_REQUEST, function(SubmissionEvent $event) {
    $submission = $event->submission;
    $success = $event->success;
    // ...
});

Spam Events#

The `beforeMarkedAsSpam` event#

The event that is triggered before the submission which has been marked as spam, is marked as spam. This event fires only after the submission has already been marked as spam.

The isValid event property can be set to false to prevent the submission from being marked as spam.

use verbb\formie\elements\Submission;
use verbb\formie\events\SubmissionMarkedAsSpamEvent;
use yii\base\Event;

Event::on(Submission::class, Submission::EVENT_BEFORE_MARKED_AS_SPAM, function(SubmissionMarkedAsSpamEvent $event) {
    $submission = $event->submission;
    $isNew = $event->isNew;
    $isValid = $event->isValid;
    // ...
});

The `beforeSpamCheck` event#

The event that is triggered before spam checks are carried out. These are not captcha checks, but Formie's spam checking like keywords.

You can use $event->submission->isSpam to modify the behaviour of whether Formie identifies the submission as spam or not.

use verbb\formie\events\SubmissionSpamCheckEvent;
use verbb\formie\services\Submissions;
use yii\base\Event;

Event::on(Submissions::class, Submissions::EVENT_BEFORE_SPAM_CHECK, function(SubmissionSpamCheckEvent $event) {
    $submission = $event->submission;

    // Flag this submission as spam
    $event->submission->isSpam = true;
});

The `afterSpamCheck` event#

The event that is triggered after spam checks have been carried out. These are not captcha checks, but Formie's spam checking like keywords.

You can use $event->submission->isSpam to modify the behaviour of whether Formie identifies the submission as spam or not.

use verbb\formie\events\SubmissionSpamCheckEvent;
use verbb\formie\services\Submissions;
use yii\base\Event;

Event::on(Submissions::class, Submissions::EVENT_AFTER_SPAM_CHECK, function(SubmissionSpamCheckEvent $event) {
    $submission = $event->submission;

    // Flag this submission as spam
    $event->submission->isSpam = true;
});

Fields Events#

The `registerFields` event#

The event that is triggered for registration of additional fields.

use verbb\formie\events\RegisterFieldsEvent;
use verbb\formie\services\Fields;
use yii\base\Event;

Event::on(Fields::class, Fields::EVENT_REGISTER_FIELDS, function(RegisterFieldsEvent $event) {
    $event->fields[] = MyField::class;
    // ...
});

The `registerLabelPositions` event#

The event that is triggered for registration of additional label positions.

use verbb\formie\events\RegisterFieldOptionsEvent;
use verbb\formie\services\Fields;
use yii\base\Event;

Event::on(Fields::class, Fields::EVENT_REGISTER_LABEL_POSITIONS, function(RegisterFieldOptionsEvent $event) {
    $fields = $event->fields;
    $options = $event->options;
    // ...
});

The `registerInstructionsPositions` event#

The event that is triggered for registration of additional instructions positions.

use verbb\formie\events\RegisterFieldOptionsEvent;
use verbb\formie\services\Fields;
use yii\base\Event;

Event::on(Fields::class, Fields::EVENT_REGISTER_INSTRUCTIONS_POSITIONS, function(RegisterFieldOptionsEvent $event) {
    $fields = $event->fields;
    $options = $event->options;
    // ...
});

The `modifyExistingFields` event#

The event that is triggered to allow modifying of available existing fields to select from.

use verbb\formie\events\ModifyExistingFieldsEvent;
use verbb\formie\services\Fields;
use yii\base\Event;

Event::on(Fields::class, Fields::EVENT_MODIFY_EXISTING_FIELDS, function(ModifyExistingFieldsEvent $event) {
    $fields = $event->fields;
    // ...
});

The `modifyFieldConfig` event#

The event that is triggered to allow modification of the config for fields, used in the form builder.

use verbb\formie\events\ModifyFieldConfigEvent;
use verbb\formie\services\Fields;
use yii\base\Event;

Event::on(Fields::class, Fields::EVENT_MODIFY_FIELD_CONFIG, function(ModifyFieldConfigEvent $event) {
    $config = $event->config;
    // ...
});

The `modifyFieldRowConfig` event#

The event that is triggered to allow modification of the config for rows, used in the form builder.

use verbb\formie\events\ModifyFieldRowConfigEvent;
use verbb\formie\services\Fields;
use yii\base\Event;

Event::on(Fields::class, Fields::EVENT_MODIFY_FIELD_ROW_CONFIG, function(ModifyFieldRowConfigEvent $event) {
    $config = $event->config;
    // ...
});

The `beforeSaveFieldRow` event#

The event that is triggered before the field's row is saved.

use verbb\formie\events\FieldRowEvent;
use verbb\formie\services\Fields;
use yii\base\Event;

Event::on(Fields::class, Fields::EVENT_BEFORE_SAVE_FIELD_ROW, function(FieldRowEvent $event) {
    $row = $event->row;
    $isNew = $event->isNew;
    // ...
});

The `afterSaveFieldRow` event#

The event that is triggered after the field's row is saved.

use verbb\formie\events\FieldRowEvent;
use verbb\formie\services\Fields;
use yii\base\Event;

Event::on(Fields::class, Fields::EVENT_AFTER_SAVE_FIELD_ROW, function(FieldRowEvent $event) {
    $row = $event->row;
    $isNew = $event->isNew;
    // ...
});

The `beforeSaveFieldPage` event#

The event that is triggered before the field's page is saved.

use verbb\formie\events\FieldPageEvent;
use verbb\formie\services\Fields;
use yii\base\Event;

Event::on(Fields::class, Fields::EVENT_BEFORE_SAVE_FIELD_PAGE, function(FieldPageEvent $event) {
    $page = $event->page;
    $isNew = $event->isNew;
    // ...
});

The `afterSaveFieldPage` event#

The event that is triggered after the field's page is saved.

use verbb\formie\events\FieldPageEvent;
use verbb\formie\services\Fields;
use yii\base\Event;

Event::on(Fields::class, Fields::EVENT_AFTER_SAVE_FIELD_PAGE, function(FieldPageEvent $event) {
    $page = $event->page;
    $isNew = $event->isNew;
    // ...
});

Field Events#

The `modifyDefaultValue` event#

The event that is triggered when preparing a field's default value. You can use this on any class that includes the FormFieldTrait trait.