README

Repository: https://gitlab.sgalinski.de/typo3/sg_forms

Please report bugs here: https://gitlab.sgalinski.de/typo3/sg_forms

About

This extension provides additional functionality for the forms extension

The backend Form Submissions module provides:

a form overview with submission counts
a root selection view listing pages that contain form submissions
an explicit empty state when no form submissions exist on any accessible page
grouped submission list view per form (paginated)
single submission detail view
in-context actions (back, export CSV, delete)
filter-aware empty states
CSV exports with contextual filenames (sgforms-*.csv)
per-form configurable visible columns in submission list
"new since last visit" indicators in form overview
language-aware frontend page links in submission detail views
translation-aware submission grouping by main form identifier
restoring a deleted main form definition also restores related deleted translation files

Legacy submissions without a stored language context continue to link to the default language version of the frontend page in the submission detail view.

Database Schema

The internal submission table is declared in TCA. ext_tables.sql remains the authoritative source for its existing primary key, parent index, and legacy signed integer columns until the project-wide schema migration is verified.

Setup

Setup custom forms storage

All you need to be able to store the form yaml files in our project theme is to create the following folder: web/typo3conf/ext/project_theme/Resources/Private/Forms**

Don't forget to include the Typoscript in your template!

CAPTCHA protection

Enable CAPTCHA for an individual form with the Enable CAPTCHA checkbox in the form editor. The globally enabled provider, its credentials, rendering and server-side validation are configured exclusively by sg_captcha. Failed requests are redisplayed with the shared CAPTCHA validation message, including programmatic submissions without browser constraint validation.

Default spam protection

All frontend forms, including existing form definitions, receive the default spam check. A signed challenge is bound to the form and site. Final submissions made in less than five seconds, with a missing, expired or reused challenge, or beyond the submission rate limit are rejected before finishers run. The existing honeypot remains enabled unless Disable honeypot is selected; Check link spam and CAPTCHA remain opt-in.

The challenge endpoint is /sg-forms/spam-challenge/. JavaScript adds the token to the form and preserves it across multi-step forms in sessionStorage; a same-origin image sets an HttpOnly cookie as a fallback. No form definition or Fluid template changes are required.

The only spam-protection option in Extension Configuration is Enable automatic spam protection (enableDefaultSpamProtection, enabled by default). Temporarily disable it if the automatic check prevents legitimate submissions, for example while resolving a blocked challenge endpoint. Re-enable it after fixing the cause. This switch affects the signed challenge, timing check and rate limits; honeypot, link checks and CAPTCHA keep their own settings.

The protection uses fixed limits maintained in the services:

Check	Fixed limit	Scope and purpose
Minimum delay	5 seconds after challenge issuance	Reject immediate automated submissions; elapsed time carries across form steps.
Challenge validity	2 hours	Allow longer editing sessions while limiting token and replay-cache lifetime.
Challenge requests	60 per minute	Per client IP and site across all forms; includes JavaScript and fallback image requests.
Accepted submissions	8 per minute	Per client IP, form and site; prevent repeated submissions and finisher execution.

Rate limits use fixed one-minute buckets, not a rolling window. Visitors sharing a public IP also share the corresponding limits. Changing form identifiers cannot bypass the challenge-request limit. These implementation limits are not Extension Configuration options.

Double Opt-In finisher

TYPO3 14 forms can request a double opt-in through the Request double opt-in finisher. It sends the configured sg_mail template to the selected email form field. Leave the template key empty to create a generic, form-specific sg_mail template automatically on the first submission. The mail receives all form-value markers plus {doubleOptInUrl}. The public GET /double-opt-in/confirm/?token=... middleware hashes the token, confirms it once, sends the optional follow-up sg_mail template, and redirects to the configured confirmation page without the token.

Configure the email field, DOI template, confirmation page UID, validity in hours, status-field name, and optional follow-up recipients/CC/BCC/reply-to in the Form Editor. doubleOptInConfirmed is the default status field. The submission is always stored, whether or not SaveSubmissionFinisher is additionally configured. Its value is stored as 0 and becomes 1 atomically at confirmation. Enable Send follow-up mail to send a post-confirmation mail; leaving its template key empty creates a generic form-specific template automatically.

When both finishers are configured, they share one submission identifier regardless of their order and never create a duplicate submission. sg_mail must be installed and the selected templates must exist. The existing sgforms:deleteOldFormSubmissions retention task removes expired pending DOI records immediately. Confirmed DOI records, including confirmed_at as the confirmation evidence, remain until the configured submission retention ends. Expiry is enforced immediately even before cleanup runs.

PDF Finisher

The PdfFinisher can fill an existing PDF form with submitted form values and optionally attach it to admin/user mails. Filling PDF forms requires mikehaertl/php-pdftk and a working pdftk binary on the server.

For local DDEV environments, make sure pdftk is installed in the web container via .ddev/config.yaml:

webimage_extra_packages: [ build-essential, python3, pdftk]

In the form editor:

Add the Fill PDF with form values finisher.
Select a PDF template file (sys_file with AcroForm fields).
Click Load PDF fields to import all PDF field names into the mapping table.
Map each imported PDF field to a TYPO3 form field identifier (Text, Textarea, Email, Checkbox, LinkedCheckbox, RadioButton, SingleSelect, MultiSelect, CountrySelect) or to a virtual value (CURRENT_DATE, CURRENT_TIME, CURRENT_DATETIME, CURRENT_TIMESTAMP).
Optionally enable Start generated PDF download on confirmation page (one-time, deletes file after first access) to automatically trigger the PDF download after submit.
Flatten generated PDF (make it non-editable) is enabled by default. Disable it if you want to keep output fields editable/highlighted.

For checkbox/radio/select mappings, the PDF field name and PDF export value definitions must match the TYPO3 values you submit (for example the selected radio option value). The editor currently does not enforce type compatibility, so integrators/editors need to ensure the mapping is semantically correct.

Generated PDFs are stored in fileadmin/sg_forms/Temp/PdfAttachments. The frontend download link uses a temporary token (default TTL: 1 hour) and is consumed on first valid access. On this first access, the generated PDF is streamed and then deleted. Integrators should still schedule cleanup for this directory, because generated PDFs can remain there when no frontend download is rendered/clicked, for example when PDFs are only attached to emails. Schedule the dedicated form submission PDF cleanup command for this:

vendor/bin/typo3 sgforms:cleanup:form-submission-pdfs --retention-period=24

The retention period is specified in hours. Adjust it to the project's retention requirements. Form Framework upload folders in 1:/form_uploads/ are cleaned up by TYPO3 core's form:cleanup:uploads command.

The one-time download URL is GET /api/public/v1/forms/pdf-download?token={token}. Invalid or expired tokens return a 404 RFC 7807 Problem JSON response; valid downloads are streamed with no-store cache headers.

Extension Configuration

Toggle Translation Grouping

By default, the backend module groups translated form definitions under their parent form. If you want to disable this behavior and see all form definitions as separate entries (e.g., in multi-site setups with separate language handling), you can toggle this behavior in the extension configuration of sg_forms in the TYPO3 Backend.

The setting groupTranslations can be found in the extension configuration under the "general" category.

Search in Form Manager

The overridden Form Manager view includes a search field above the form list. It filters forms by:

form name (label)
form persistenceIdentifier

sgalinski / sg-forms

Package info

Security

Statistics