Freeform for Craft

2.x

• 5.x⚙ Beta
• 4.x✓ Latest
• 3.x
• 2.x
• 1.x

Plugin Store

# Events & Hooks

If you wish to extend the capabilities of Freeform, you can use any of the events and hooks below:

# Forms

\Solspace\Freeform\Services\FormsService

• ::EVENT_BEFORE_SUBMIT #
  • Called when a form is submitted, but before a submission element is being made
  • \Solspace\Freeform\Events\Forms\BeforeSubmitEvent contains these methods:
    • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
• ::EVENT_AFTER_SUBMIT #
  • Called after processing form and saving the submission element
  • \Solspace\Freeform\Events\Forms\AfterSubmitEvent contains these methods:
    • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
    • getSubmission() - returns \Solspace\Freeform\Elements\Submission
• ::EVENT_BEFORE_SAVE #
  • Called before saving a form
  • \Solspace\Freeform\Events\Forms\SaveEvent contains these methods:
    • getModel() - returns \Solspace\Freeform\Models\FormModel
    • isNew() - bool
• ::EVENT_AFTER_SAVE #
  • Called after saving a form
  • \Solspace\Freeform\Events\Forms\SaveEvent contains these methods:
    • getModel() - returns \Solspace\Freeform\Models\FormModel
    • isNew() - bool
• ::EVENT_BEFORE_DELETE #
  • Called before deleting a form
  • \Solspace\Freeform\Events\Forms\DeleteEvent contains these methods:
    • getModel() - returns \Solspace\Freeform\Models\FormModel
• ::EVENT_AFTER_DELETE #
  • Called after deleting a form
  • \Solspace\Freeform\Events\Forms\DeleteEvent contains these methods:
    • getModel() - returns \Solspace\Freeform\Models\FormModel
• ::EVENT_RENDER_OPENING_TAG #
  • Called when rendering the opening tag of a form
  • \Solspace\Freeform\Events\Forms\FormRenderEvent contains these methods:
    • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
    • getCompiledOutput() - returns a string of the rendered form opening tag and inputs
    • appendToOutput(string $value) - append a chunk of your string to the output
    • appendJsToOutput(string $value) - append javascript to the form opening tag. Wraps it in <script></script> tags automatically
    • appendCssToOutput(string $value) - append css to the form opening tag. Wraps it in <style></style> tags automatically
• ::EVENT_RENDER_CLOSING_TAG #
  • Called when rendering the closing tag of a form
  • \Solspace\Freeform\Events\Forms\FormRenderEvent contains these methods:
    • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
    • getCompiledOutput() - returns a string of the rendered form opening tag and inputs
    • appendToOutput(string $value) - append a chunk of your string to the output
    • appendJsToOutput(string $value) - append javascript to the form opening tag. Wraps it in <script></script> tags automatically
    • appendCssToOutput(string $value) - append css to the form opening tag. Wraps it in <style></style> tags automatically
• ::EVENT_ATTACH_FORM_ATTRIBUTES #
  • Called when attaching attributes to a form
  • \Solspace\Freeform\Events\Forms\FormRenderEvent contains these methods:
    • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
    • getAttributes() - returns an array of existing attributes specified for the form
    • attachAttribute(string $name, mixed $value) - attach an attribute to the form
    • removeAttribute(string $name) - removes an attribute from the attribute stack
• ::EVENT_FORM_VALIDATE #
  • Called when validating the form
  • \Solspace\Freeform\Events\Forms\FormValidateEvent contains these methods:
    • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
    • isFormValid() - bool
    • addErrorToForm(string $message) - allows you to add an error message to the form
• ::EVENT_AFTER_GENERATE_RETURN_URL #
  • Called after generating a return URL, allowing you to modify the return URL of a form.
  • \Solspace\Freeform\Events\Forms\ReturnUrlEvent contains these methods:
    • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
    • getSubmission() - returns \Solspace\Freeform\Elements\Submission
    • getReturnUrl() - allows you to get the currently set Return URL
    • setReturnUrl(string $returnUrl) - allows you to set a custom Return URL

# Submissions

\Solspace\Freeform\Services\SubmissionsService

• ::EVENT_BEFORE_SUBMIT #
  • Called before saving a submission
  • \Solspace\Freeform\Events\Submissions\SubmitEvent contains these methods:
    • getElement() - returns \Solspace\Freeform\Elements\Submission
    • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
• ::EVENT_AFTER_SUBMIT #
  • Called after saving a submission
  • \Solspace\Freeform\Events\Submissions\SubmitEvent contains these methods:
    • getElement() - returns \Solspace\Freeform\Elements\Submission
    • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
• ::EVENT_BEFORE_DELETE #
  • Called before deleting a submission
  • \Solspace\Freeform\Events\Submissions\DeleteEvent contains these methods:
    • getSubmission() - returns \Solspace\Freeform\Elements\Submission
• ::EVENT_AFTER_DELETE #
  • Called after deleting a submission
  • \Solspace\Freeform\Events\Submissions\DeleteEvent contains these methods:
    • getSubmission() - returns \Solspace\Freeform\Elements\Submission

# Fields

\Solspace\Freeform\Services\FieldsService

• ::EVENT_BEFORE_SAVE #
  • Called before saving a field
  • \Solspace\Freeform\Events\Fields\SaveEvent contains these methods:
    • getModel() - returns \Solspace\Freeform\Models\FieldModel
    • isNew() - bool
• ::EVENT_AFTER_SAVE #
  • Called after saving a field
  • \Solspace\Freeform\Events\Fields\SaveEvent contains these methods:
    • getModel() - returns \Solspace\Freeform\Models\FieldModel
    • isNew() - bool
• ::EVENT_BEFORE_DELETE #
  • Called before deleting a field
  • \Solspace\Freeform\Events\Fields\DeleteEvent contains these methods:
    • getModel() - returns \Solspace\Freeform\Models\FieldModel
• ::EVENT_AFTER_DELETE #
  • Called after deleting a field
  • \Solspace\Freeform\Events\Fields\DeleteEvent contains these methods:
    • getModel() - returns \Solspace\Freeform\Models\FieldModel
• ::EVENT_BEFORE_VALIDATE #
  • Called before validating a field
  • \Solspace\Freeform\Events\Fields\ValidateEvent contains these methods:
    • getField() - returns \Solspace\Freeform\Library\Composer\Components\AbstractField
    • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
• ::EVENT_AFTER_VALIDATE #
  • Called after validating a field
  • \Solspace\Freeform\Events\Fields\ValidateEvent contains these methods:
    • getField() - returns \Solspace\Freeform\Library\Composer\Components\AbstractField
    • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form

# Notifications

\Solspace\Freeform\Services\NotificationsService

• ::EVENT_BEFORE_SAVE #
  • Called before saving a notification
  • \Solspace\Freeform\Events\Notifications\SaveEvent contains these methods:
    • getRecord() - returns \Solspace\Freeform\Records\NotificationRecord
    • isNew() - bool
• ::EVENT_AFTER_SAVE #
  • Called after saving a notification
  • \Solspace\Freeform\Events\Notifications\SaveEvent contains these methods:
    • getRecord() - returns \Solspace\Freeform\Records\NotificationRecord
    • isNew() - bool
• ::EVENT_BEFORE_DELETE #
  • Called before deleting a notification
  • \Solspace\Freeform\Events\Notifications\DeleteEvent contains these methods:
    • getRecord() - returns \Solspace\Freeform\Records\NotificationRecord
• ::EVENT_AFTER_DELETE #
  • Called after deleting a notification
  • \Solspace\Freeform\Events\Notifications\DeleteEvent contains these methods:
    • getRecord() - returns \Solspace\Freeform\Records\NotificationRecord

# Statuses

\Solspace\Freeform\Services\StatusesService

• ::EVENT_BEFORE_SAVE #
  • Called before saving a status
  • \Solspace\Freeform\Events\Statuses\SaveEvent contains these methods:
    • getModel() - returns \Solspace\Freeform\Models\StatusModel
    • isNew() - bool
• ::EVENT_AFTER_SAVE #
  • Called after saving a status
  • \Solspace\Freeform\Events\Statuses\SaveEvent contains these methods:
    • getModel() - returns \Solspace\Freeform\Models\StatusModel
    • isNew() - bool
• ::EVENT_BEFORE_DELETE #
  • Called before deleting a status
  • \Solspace\Freeform\Events\Statuses\DeleteEvent contains these methods:
    • getModel() - returns \Solspace\Freeform\Models\StatusModel
• ::EVENT_AFTER_DELETE #
  • Called after deleting a status
  • \Solspace\Freeform\Events\Statuses\DeleteEvent contains these methods:
    • getModel() - returns \Solspace\Freeform\Models\StatusModel

# File Uploads

\Solspace\Freeform\Services\FilesService

• ::EVENT_BEFORE_UPLOAD #
  • Called before uploading a file
  • \Solspace\Freeform\Events\Files\UploadEvent contains these methods:
    • getField() - returns \Solspace\Freeform\Library\Composer\Components\Fields\FileUploadField
• ::EVENT_AFTER_UPLOAD #
  • Called after uploading a file
  • \Solspace\Freeform\Events\Files\UploadEvent contains these methods:
    • getField() - returns \Solspace\Freeform\Library\Composer\Components\Fields\FileUploadField

# Mailing

\Solspace\Freeform\Services\MailerService

• ::EVENT_BEFORE_SEND #
  • Called before sending an email
  • \Solspace\Freeform\Events\Mailer\SendEmailEvent contains these methods:
    • getMessage() - returns \craft\mail\Message
    • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
    • getNotification() - returns \Solspace\Freeform\Library\Mailing\NotificationInterface
    • getFieldValues() - array of key-value pairs of fields and their values
    • getSubmission() - returns \Solspace\Freeform\Elements\Submission if the form is set to store data
• ::EVENT_AFTER_SEND #
  • Called after sending an email
  • \Solspace\Freeform\Events\Mailer\SendEmailEvent contains these methods:
    • getMessage() - returns \craft\mail\Message
    • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
    • getNotification() - returns \Solspace\Freeform\Library\Mailing\NotificationInterface
    • getFieldValues() - array of key-value pairs of fields and their values
    • getSubmission() - returns \Solspace\Freeform\Elements\Submission if the form is set to store data
• ::EVENT_BEFORE_RENDER 2.0.4+ #
  • Called before rendering the email message body and subject, etc
  • \Solspace\Freeform\Events\Mailer\RenderEmailEvent::__construct contains these methods:
    • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
    • getNotification() - returns \Solspace\Freeform\Library\Mailing\NotificationInterface
    • getFieldValues() - array of key-value pairs of fields and their values
    • setFieldValues(array $fieldValues) - allows you to update the field values that are passed to the email body and subject twig templates
    • getSubmission() - returns \Solspace\Freeform\Elements\Submission if the form is set to store data

# CRM Integrations

\Solspace\Freeform\Services\CrmService

• ::EVENT_BEFORE_SAVE #
  • Called before saving an integration
  • \Solspace\Freeform\Events\Integrations\SaveEvent contains these methods:
    • getModel() - returns \Solspace\Freeform\Models\IntegrationModel
    • isNew - bool
• ::EVENT_AFTER_SAVE #
  • Called after saving an integration
  • \Solspace\Freeform\Events\Integrations\SaveEvent contains these methods:
    • getModel() - returns \Solspace\Freeform\Models\IntegrationModel
    • isNew - bool
• ::EVENT_BEFORE_DELETE #
  • Called before deleting an integration
  • \Solspace\Freeform\Events\Integrations\DeleteEvent contains these methods:
    • getModel() - returns \Solspace\Freeform\Models\IntegrationModel
• ::EVENT_AFTER_DELETE #
  • Called after deleting an integration
  • \Solspace\Freeform\Events\Integrations\DeleteEvent contains these methods:
    • getModel() - returns \Solspace\Freeform\Models\IntegrationModel
• ::EVENT_BEFORE_PUSH 2.0.1+ #
  • Called before pushing data to an integration
  • \Solspace\Freeform\Events\Integrations\PushEvent contains these methods:
    • getIntegration() - returns \Solspace\Freeform\Library\Integrations\AbstractIntegration
    • getValues() - a key-value array of all values to be pushed to the integration
    • setValues(array $values) - override all of the values with a new key-value array
    • addValue(string $key, mixed $value) - add or override any key/value in the set
• ::EVENT_AFTER_PUSH 2.0.1+ #
  • Called after pushing data to an integration
  • \Solspace\Freeform\Events\Integrations\PushEvent contains these methods:
    • getIntegration() - returns \Solspace\Freeform\Library\Integrations\AbstractIntegration
    • getValues() - a key-value array of all values to be pushed to the integration
• ::EVENT_AFTER_RESPONSE 2.5.6+ #
  • Called after a response is received from pushing to the integration
  • \Solspace\Freeform\Events\Integrations\IntegrationResponseEvent contains these methods:
    • getIntegration() - returns \Solspace\Freeform\Library\Integrations\AbstractIntegration instance
    • getResponse() - returns \Psr\Http\Message\ResponseInterface
    • getResponseBodyAsString() - returns the ResponseInterface object's body as string, which will usually contain the JSON response as string

# Mailing List Integrations

\Solspace\Freeform\Services\MailingListsService

• ::EVENT_BEFORE_SAVE #
  • Called before saving an integration
  • \Solspace\Freeform\Events\Integrations\SaveEvent contains these methods:
    • getModel() - returns \Solspace\Freeform\Models\IntegrationModel
    • isNew - bool
• ::EVENT_AFTER_SAVE #
  • Called after saving an integration
  • \Solspace\Freeform\Events\Integrations\SaveEvent contains these methods:
    • getModel() - returns \Solspace\Freeform\Models\IntegrationModel
    • isNew - bool
• ::EVENT_BEFORE_DELETE #
  • Called before deleting an integration
  • \Solspace\Freeform\Events\Integrations\DeleteEvent contains these methods:
    • getModel() - returns \Solspace\Freeform\Models\IntegrationModel
• ::EVENT_AFTER_DELETE #
  • Called after deleting an integration
  • \Solspace\Freeform\Events\Integrations\DeleteEvent contains these methods:
    • getModel() - returns \Solspace\Freeform\Models\IntegrationModel
• ::EVENT_AFTER_RESPONSE 2.5.6+ #
  • Called after a response is received from pushing to the integration
  • \Solspace\Freeform\Events\Integrations\IntegrationResponseEvent contains these methods:
    • getIntegration() - returns \Solspace\Freeform\Library\Integrations\AbstractIntegration instance
    • getResponse() - returns \Psr\Http\Message\ResponseInterface
    • getResponseBodyAsString() - returns the ResponseInterface object's body as string, which will usually contain the JSON response as string

# Usage Examples

In your plugin's ::init() method, subscribe to any of these events by using the Event::on() static method:

<?php

namespace Craft;

class YourPlugin extends BasePlugin
{
  public function init()
  {
    parent::init();

    // Forms
    Event::on(
      FormsService::class,
      FormsService::EVENT_BEFORE_SAVE,
      function (SaveEvent $event) {
        $form  = $event->getModel();
        $isNew = $event->isNew();
        // Do something with this data
      }
    );

    // Submissions
    Event::on(
      SubmissionsService::class,
      SubmissionsService::EVENT_AFTER_SUBMIT,
      function (SubmitEvent $event) {
        $submission = $event->getElement();
        $form       = $event->getForm();

        // Get a specific field value
        $value = $form->get('firstName')->getValue();

        // Iterate over all posted fields and get their values
        foreach ($form->getLayout()->getFields() as $field) {

            // Bypass fields such as HTML or Submit, etc.
            if ($field instanceof NoStorageInterface) {
                continue;
            }

            $field->getValue();
        }

        // Do something with this data
      }
    );

    // Fields
    Event::on(
      FieldsService::class,
      FieldsService::EVENT_BEFORE_DELETE,
      function (DeleteEvent $event) {
        $fieldModel = $event->getModel();
        // Do something with this data
      }
    );

    // Notifications
    Event::on(
      NotificationsService::class,
      NotificationsService::EVENT_AFTER_DELETE,
      function (DeleteEvent $event) {
        $notificationRecord = $event->getRecord();
        // Do something with this data
      }
    );

    // Statuses
    Event::on(
      StatusesService::class,
      StatusesService::EVENT_BEFORE_SAVE,
      function (SaveEvent $event) {
        $statusModel = $event->getModel();
        $isNew     = $event->isNew();
        // Do something with this data
      }
    );

    // File Uploads
    Event::on(
      FilesService::class,
      FilesService::EVENT_AFTER_UPLOAD,
      function (UploadEvent $event) {
        $fileUploadField = $event->getField();
        // Do something with this data
      }
    );

    // Mailing
    Event::on(
      MailerService::class,
      MailerService::EVENT_AFTER_SEND,
      function (SendEmailEvent $event) {
        $message = $event->getMessage();
        $form  = $event->getForm();
        $notification = $event->getNotification();
        $fieldValues  = $event->getFieldValues();
        $submission   = $event->getSubmission();
        // Do something with this data
      }
    );

    // CRM Integrations
    Event::on(
      CrmService::class,
      CrmService::EVENT_BEFORE_SAVE,
      function (SaveEvent $event) {
        $integrationModel = $event->getModel();
        // Do something with this data
      }
    );

    Event::on(
      CrmService::class,
      CrmService::EVENT_AFTER_RESPONSE,
      function (IntegrationResponseEvent $event) {
        $integration = $event->getIntegration();
        $response  = $event->getResponse();
        $jsonString  = $event->getResponseBodyAsString();

        $object = json_decode($jsonString);

        // Do something with the response object
      }
    );

    // Mailing List Integrations
    Event::on(
      MailingListsService::class,
      MailingListsService::EVENT_BEFORE_SAVE,
      function (SaveEvent $event) {
        $integrationModel = $event->getModel();
        // Do something with this data
      }
    );

    Event::on(
      MailingListsService::class,
      MailingListsService::EVENT_AFTER_RESPONSE,
      function (IntegrationResponseEvent $event) {
        $integration = $event->getIntegration();
        $response  = $event->getResponse();
        $jsonString  = $event->getResponseBodyAsString();

        $object = json_decode($jsonString);

        // Do something with the response object
      }
    );
  }
}