Double opt-in for EXT:form

• Consent finisher
• Validation plugin
• Scheduler task
• Dashboard widget

Extension key

form_consent

Package name

eliashaeussler/typo3-form-consent

Version

3.1

Language

en

Author

Elias Häußler & contributors

License

This extension documentation is published under the CC BY-NC-SA 4.0 (Creative Commons) license.

An extension for TYPO3 CMS that adds double opt-in functionality to EXT:form. It allows the dynamic adaptation of the entire double opt-in process using various events. In addition, the extension integrates seamlessly into TYPO3, for example to delete expired consents in compliance with the GDPR.

Introduction

Installation

composer require eliashaeussler/typo3-form-consent

Configuration

Learn what configuration options are available on the following pages:

Form finisher configuration

The consent finisher can be configured with the following options:

SiteSet configuration

The extension ships with a site set called eliashaeussler/typo3-form-consent. It can be used as drop-in replacement for TypoScript in TYPO3 v13.1 or later.

The following settings are available for the site set:

TypoScript configuration

The following global TypoScript configuration is available:

Extension configuration

The extension currently provides the following configuration options:

Usage

This section describes how to properly use the extension. Before you start, make sure to add the site set as dependency to your site or include the static TypoScript provided by the extension.

Consent finisher

A new finisher Consent is available in the backend form editor. It saves all submitted form data in the database and sends a corresponding mail to either approve or dismiss a given consent.

finishers:
  -
    identifier: Consent
    options:
      subject: 'Please approve your subscription'
      recipientAddress: '{email}'
      recipientName: '{first-name} {last-name}'
      senderAddress: ''
      senderName: ''
      replyToAddress: ''
      replyToName: ''
      approvalPeriod: '86400'
      showDismissLink: true
      confirmationPid: '277'
      storagePid: '276'
      requireApproveVerification: true
      requireDismissVerification: true
  -
    identifier: SaveToDatabase
    options:
      table: tx_myextension_domain_model_subscription
      mode: insert
      databaseColumnMappings:
        consent:
          # References the consent uid
          value: '{Consent.lastInsertedConsent.uid}'

variants:
  -
    identifier: post-consent-approval-variant-1
    condition: 'isConsentApproved()'
    finishers:
      -
        identifier: EmailToReceiver
        options:
          # ...
      -
        identifier: Redirect
        options:
          # ...

Validation plugin

A plugin is required for approval or dismissal of the consent. The associated page containing the plugin must then be specified in the finisher configuration.

Scheduler task

Consents are considered "expired" if they were originally submitted with a configured approval period (read more in the consent finisher configuration) and time between consent submit and allowed approval time has passed. If consents are expired, they are not deleted by default, but remain active in the database, even though they can no longer be approved or dismissed.

For TYPO3 installations having EXT:scheduler installed, this extension provides a convenient way to remove expired consents. It adds the consent table tx_formconsent_domain_model_consent to the list of tables for which table garbage collection is supported. For the expireField option, the consent field valid_until is configured.

Dashboard widget

This extension provides a dashboard widget for installations having EXT:dashboard installed. The widget shows all currently approved, non-approved and dismissed consents as doughnut chart.

Developer corner

This section provides an insight into which development options are available and how these can be used with form consents.

Configuration API

In order to access the extension configuration, a slim PHP API exists. Each configuration option is accessible by an appropriate class method.

class Configuration

Fully qualified name

\EliasHaeussler\Typo3FormConsent\Configuration\Configuration

API to access all available extension configuration options.

getExcludedElementsFromPersistence ( )

Get all form element types that are excluded from persistence.

returntype

list<string>

Consent factory

New consents are normally built by the consent finisher, based on the current FormRuntime. In order to better separate the actual consent building process from the form submission, a dedicated consent factory is provided.

class ConsentFactory

Fully qualified name

\EliasHaeussler\Typo3FormConsent\Domain\Factory\ConsentFactory

Factory class to create new consents from a given form.

createFromForm ( $finisherOptions, $finisherContext)

Create a new form consent from the given form, derived from the given finisher options.

Tip

This method's result can be modified by listening on the ModifyConsentEvent.

param EliasHaeussler\Typo3FormConsent\Domain\Finishers\FinisherOptions $finisherOptions

Consent finisher options of the current form

param TYPO3\CMS\Form\Domain\Finishers\FinisherContext $finisherContext

The current finisher context

returntype

EliasHaeussler\Typo3FormConsent\Domain\Model\Consent

Events

Some PSR-14 events are dispatched while consents are generated or modified. This allows to step in the consent lifecycle and perform several actions, based on the actual event.

The following events are currently dispatched:

JSON type

The extension provides a custom type to persist arbitrary form values as JSON data to the database. This allows to dynamically persist values in a relatively easy and maintainable way, since the provided type implements TYPO3 core API. The resulting values are actually JSON-encoded strings.

class JsonType

Fully qualified name

\EliasHaeussler\Typo3FormConsent\Type\JsonType

Type implementing TYPO3's \TYPO3\CMS\Core\Type\TypeInterface that accepts and stores JSON-encoded strings.

static fromArray ( $data)

Create a new JSON type from the given array.

param array $data

Array to persist, will be JSON-encoded

returntype

EliasHaeussler\Typo3FormConsent\Type\JsonType

toArray ( )

Return current JSON-encoded string as parsed array.

returntype

array

Migration

This page lists all notable changes and required migrations when upgrading to a new major version of this extension.

Contributing

Thanks for considering contributing to this extension! Since it is an open source product, its successful further development depends largely on improving and optimizing it together.

The development of this extension follows the official TYPO3 coding standards. To ensure the stability and cleanliness of the code, various code quality tools are used and most components are covered with test cases. In addition, we use DDEV for local development. Make sure to set it up as described below. For continuous integration, we use GitHub Actions.

git clone https://github.com/eliashaeussler/typo3-form-consent.git
cd typo3-form-consent

ddev start

# All analyzers
ddev cgl analyze

# Specific analyzers
ddev cgl analyze:dependencies

# All linters
ddev cgl lint

# Specific linters
ddev cgl lint:composer
ddev cgl lint:editorconfig
ddev cgl lint:php
ddev cgl lint:typoscript

# Fix all CGL issues
ddev cgl fix

# Fix specific CGL issues
ddev cgl fix:composer
ddev cgl fix:editorconfig
ddev cgl fix:php
ddev cgl fix:typoscript

# All static code analyzers
ddev cgl sca

# Specific static code analyzers
ddev cgl sca:php

# All tests
ddev test

# Specific tests
ddev test acceptance
ddev test functional
ddev test unit

# All tests with code coverage
ddev test coverage

# Specific tests with code coverage
ddev test coverage:acceptance
ddev test coverage:functional
ddev test coverage:unit

# Merge code coverage of all test suites
ddev test coverage:merge

open .Build/coverage/html/_merged/index.html

open .Build/log/acceptance-reports/records.html

# Rebuild and open documentation
composer docs

# Build documentation (from cache)
composer docs:build

# Open rendered documentation
composer docs:open

Sitemap