AD Form Dev Docs

Darstellung

Hook-Referenz ​

Alle Hook-Namen sind mit ad_form_ präfixiert und liegen als Konstanten in Dingfelder\AdForm\Core\Hooks. Im Add-on-Code sollte immer die Konstante verwendet werden – der String ist ein Implementierungsdetail:

php
use Dingfelder\AdForm\Core\Hooks;

add_action( Hooks::AFTER_SUBMISSION, $callback, 10, 2 );

Reservierte Namen

Drei Konstanten sind bereits vergeben, werden aber noch nirgends ausgelöst: Hooks::REGISTER_MODULES (ad_form_register_modules), Hooks::VALIDATION_RULES (ad_form_validation_rules) und Hooks::INTEGRATIONS (ad_form_integrations). Sie sind für kommende Ausbaustufen reserviert; ein Callback darauf läuft aktuell nicht.

Bootstrap ​

Läuft in Plugin::boot() auf plugins_loaded (Priorität 5), in dieser Reihenfolge: ad_form_service_providers → register() aller Provider → ad_form_register_services → boot() aller Provider → ad_form_loaded.

ad_form_service_providers ​

Filter · Hooks::SERVICE_PROVIDERS

php
apply_filters( 'ad_form_service_providers', list<ServiceProviderInterface> $providers ): array
ParameterTypBeschreibung
$providerslist<ServiceProviderInterface>Die Kern-Provider in Registrierungsreihenfolge

Die Rückgabe wird gefiltert: Alles, was kein ServiceProviderInterface ist, verschwindet kommentarlos. Anhängen statt ersetzen erhält die Kern-Reihenfolge.

php
add_filter(
	'ad_form_service_providers',
	static function ( array $providers ): array {
		$providers[] = new Acme\AdFormCrm\CrmServiceProvider();

		return $providers;
	}
);

ad_form_register_services ​

Action · Hooks::REGISTER_SERVICES

php
do_action( 'ad_form_register_services', Container $container ): void
ParameterTypBeschreibung
$containerDingfelder\AdForm\Core\ContainerService Container mit allen Kern-Bindings

Feuert nach register() und vor boot() aller Provider. Der letzte Zeitpunkt, um eigene Services zu binden oder Kern-Interfaces zu ersetzen – siehe Service Container.

ad_form_loaded ​

Action · Hooks::LOADED

php
do_action( 'ad_form_loaded', Plugin $plugin ): void
ParameterTypBeschreibung
$pluginDingfelder\AdForm\PluginGebootete Plugin-Instanz

Alles ist verfügbar: $plugin->container(), $plugin->version(), $plugin->providers().

ad_form_register_modules ​

Reserviert · Hooks::REGISTER_MODULES · wird aktuell nicht ausgelöst.

Forms ​

ad_form_form_definition ​

Filter · Hooks::FORM_DEFINITION · FormDefinition::sanitize()

php
apply_filters( 'ad_form_form_definition', array $clean, array $data ): array
ParameterTypBeschreibung
$cleanarray<string, mixed>Sanitisierte Definition (version, settings, fields, layout, steps, actions, conditions, styles)
$dataarray<string, mixed>Rohe Eingabe vor dem Sanitizing

Läuft bei jedem Speichern. Eine Rückgabe, die kein Array ist, wird ignoriert.

ad_form_form_query ​

Filter · Hooks::FORM_QUERY · FormRepository::paginate()

php
apply_filters( 'ad_form_form_query', FormQuery $query ): FormQuery

Nur eine Rückgabe vom Typ FormQuery wird übernommen, sonst bleibt die ursprüngliche Query bestehen.

ad_form_before_form_save ​

Action · Hooks::BEFORE_FORM_SAVE · FormService::create() und FormService::update()

php
do_action( 'ad_form_before_form_save', Form $form, array $input ): void
ParameterTypBeschreibung
$formDingfelder\AdForm\Forms\FormEntity vor dem Schreiben; bei create() ist id() noch 0
$inputarray<string, mixed>Rohe Eingabedaten

Form ist unveränderlich – der Hook eignet sich zum Beobachten und Validieren, nicht zum Ändern.

ad_form_after_form_save ​

Action · Hooks::AFTER_FORM_SAVE

php
do_action( 'ad_form_after_form_save', Form $form, bool $created ): void
ParameterTypBeschreibung
$formFormGespeicherte Entity, id() und version() sind gesetzt
$createdbooltrue beim Anlegen, false beim Aktualisieren

ad_form_after_form_delete ​

Action · Hooks::AFTER_FORM_DELETE

php
do_action( 'ad_form_after_form_delete', Form $form, bool $force ): void
ParameterTypBeschreibung
$formFormGelöschtes Formular
$forcebooltrue, wenn trotz vorhandener Einträge gelöscht wurde

ad_form_form_rest_item ​

Filter · Hooks::FORM_REST_ITEM · Form::to_rest_array()

php
apply_filters( 'ad_form_form_rest_item', array $item, Form $form ): array

Der richtige Ort, um eigene Felder in die REST-Darstellung eines Formulars zu hängen.

Fields ​

ad_form_register_fields ​

Action · Hooks::REGISTER_FIELDS · FieldRegistry::boot()

php
do_action( 'ad_form_register_fields', FieldRegistry $registry ): void
ParameterTypBeschreibung
$registryDingfelder\AdForm\Fields\FieldRegistryRegistry mit bereits registrierten Kern-Feldtypen

Feuert genau einmal pro Request. Der empfohlene Weg für eigene Feldtypen – siehe Eigene Feldtypen.

ad_form_fields ​

Filter · Hooks::FIELDS · direkt nach ad_form_register_fields

php
apply_filters( 'ad_form_fields', array $fields, FieldRegistry $registry ): array
ParameterTypBeschreibung
$fieldsarray<string, FieldInterface>Map type => Feldtyp
$registryFieldRegistryRegistry-Instanz

Die Rückgabe wird neu nach type() indiziert; Einträge, die kein FieldInterface sind, fallen raus. Zum Entfernen eines Kern-Feldtyps geeignet.

ad_form_condition_operators ​

Filter · Hooks::CONDITION_OPERATORS · ConditionEngine::operators()

php
apply_filters( 'ad_form_condition_operators', array $operators ): array
ParameterTypBeschreibung
$operatorslist<array{id: string, label: string, needs_value: bool}>Operator-Katalog für Builder und REST

Ein neuer Eintrag erscheint im Builder – die Auswertung muss zusätzlich in der Condition-Engine und im Frontend-JavaScript existieren.

ad_form_validation_rules ​

Reserviert · Hooks::VALIDATION_RULES · wird aktuell nicht ausgelöst. Validierung läuft heute über FieldInterface::validate_submitted_value().

Actions ​

ad_form_actions ​

Filter · Hooks::ACTIONS · ActionRegistry::boot()

php
apply_filters( 'ad_form_actions', array $actions, ActionRegistry $registry ): array
ParameterTypBeschreibung
$actionsarray<string, ActionInterface>Map type => Action
$registryDingfelder\AdForm\Actions\ActionRegistryRegistry-Instanz

Der einzige Weg, eigene Submit-Actions zu registrieren – siehe Eigene Submit-Actions.

ad_form_before_action ​

Action · Hooks::BEFORE_ACTION · ActionRunner::run()

php
do_action( 'ad_form_before_action', string $type, array $settings, ActionContext $context ): void
ParameterTypBeschreibung
$typestringAction-Typ, bereits durch sanitize_key() gelaufen
$settingsarray<string, mixed>Einstellungen aus der Definition
$contextActionContextFormular und gespeicherte Übermittlung

Feuert erst, nachdem Bedingungen geprüft und ein Handler gefunden wurde.

ad_form_after_action ​

Action · Hooks::AFTER_ACTION

php
do_action( 'ad_form_after_action', string $type, ActionResultInterface $result, ActionContext $context ): void
ParameterTypBeschreibung
$typestringAction-Typ
$resultActionResultInterfaceErgebnis, auch bei Misserfolg
$contextActionContextKontext

Feuert immer – auch wenn run() eine Exception geworfen hat. In dem Fall ist $result->code() gleich exception.

ad_form_merge_tags ​

Filter · Hooks::MERGE_TAGS · MergeTagEngine::expand()

php
apply_filters( 'ad_form_merge_tags', array $tags, ActionContext $context, string $mode ): array
ParameterTypBeschreibung
$tagsarray<string, string>Map Tag → Ersetzung, z. B. {form:title}
$contextActionContextKontext der laufenden Action
$modestringMergeTagEngine::MODE_PLAIN oder MergeTagEngine::MODE_HTML

Nur String-Schlüssel werden übernommen. Im HTML-Modus muss der Wert bereits escaped sein.

Submissions ​

Reihenfolge eines erfolgreichen Submits: ad_form_before_validation → ad_form_after_validation → ad_form_before_submission → Speichern → ad_form_after_submission → Submit-Actions.

ad_form_before_validation ​

Action · Hooks::BEFORE_VALIDATION · SubmitService::submit()

php
do_action( 'ad_form_before_validation', Form $form, array $values ): void
ParameterTypBeschreibung
$formFormFormular
$valuesarray<string, mixed>Rohe übermittelte Werte, indiziert nach Field-Key

ad_form_after_validation ​

Action · Hooks::AFTER_VALIDATION

php
do_action( 'ad_form_after_validation', Form $form, array $clean, array $errors ): void
ParameterTypBeschreibung
$formFormFormular
$cleanarray<string, mixed>Sanitisierte, sichtbare Werte
$errorsarray<string, string>Field-Key → Fehlermeldung

Feuert auch, wenn Fehler vorliegen – direkt danach wirft der Service eine SubmitException::validation().

ad_form_before_submission ​

Action · Hooks::BEFORE_SUBMISSION

php
do_action( 'ad_form_before_submission', Form $form, array $clean, RequestContext $context ): void
ParameterTypBeschreibung
$formFormFormular
$cleanarray<string, mixed>Validierte Werte
$contextDingfelder\AdForm\Submissions\RequestContextRequest-Metadaten: source(), ip_hash(), user_agent(), user_id()

Feuert nur, wenn die Validierung fehlerfrei war, aber bevor geschrieben wird. Es gibt noch keine Entry-ID.

ad_form_after_submission ​

Action · Hooks::AFTER_SUBMISSION

php
do_action( 'ad_form_after_submission', Submission $submission, Form $form ): void
ParameterTypBeschreibung
$submissionDingfelder\AdForm\Submissions\SubmissionGespeicherter Eintrag inklusive id() und uuid()
$formFormFormular

Der wichtigste Integrationspunkt. Honeypot-Treffer erreichen ihn nie. Der ActionRunner hängt hier mit Priorität 10 und zwei Argumenten.

php
use Dingfelder\AdForm\Forms\Form;
use Dingfelder\AdForm\Submissions\Submission;

add_action(
	'ad_form_after_submission',
	static function ( Submission $submission, Form $form ): void {
		// $submission->payload() enthält die Feldwerte.
	},
	10,
	2
);

ad_form_submission_query ​

Filter · Hooks::SUBMISSION_QUERY · SubmissionRepository::paginate()

php
apply_filters( 'ad_form_submission_query', SubmissionQuery $query ): SubmissionQuery

Nur eine Rückgabe vom Typ SubmissionQuery wird übernommen.

ad_form_submission_rest_item ​

Filter · Hooks::SUBMISSION_REST_ITEM · Submission::to_rest_array()

php
apply_filters( 'ad_form_submission_rest_item', array $item, Submission $submission ): array

ad_form_after_entry_status ​

Action · Hooks::AFTER_ENTRY_STATUS · SubmissionService

php
do_action( 'ad_form_after_entry_status', Submission $entry, string $action ): void
ParameterTypBeschreibung
$entrySubmissionEintrag nach der Änderung
$actionstringDer neue Status-Wert (unread, read, spam, trash) oder star / unstar

Die Admin-Aktionen unspam und restore setzen jeweils einen Status – der Hook meldet deshalb den resultierenden Status, nicht den Namen der ausgelösten Aktion.

ad_form_after_entry_delete ​

Action · Hooks::AFTER_ENTRY_DELETE

php
do_action( 'ad_form_after_entry_delete', int $id, int $form_id ): void
ParameterTypBeschreibung
$idintID des endgültig gelöschten Eintrags
$form_idintZugehöriges Formular

Feuert nur beim endgültigen Löschen, nicht beim Verschieben in den Papierkorb. Die Entity ist zu diesem Zeitpunkt bereits weg – deshalb nur IDs.

REST ​

ad_form_rest_routes ​

Action · Hooks::REST_ROUTES · innerhalb von rest_api_init

php
do_action( 'ad_form_rest_routes', Container $container ): void
ParameterTypBeschreibung
$containerContainerService Container

Feuert, nachdem alle Kern-Controller ihre Routen registriert haben. Eigene Routen im Namespace ad-form/v1:

php
use Dingfelder\AdForm\Core\Container;
use Dingfelder\AdForm\Core\PluginInfo;
use Dingfelder\AdForm\Security\Capabilities;

add_action(
	'ad_form_rest_routes',
	static function ( Container $container ): void {
		register_rest_route(
			PluginInfo::REST_NAMESPACE,
			'/reports',
			array(
				'methods'             => 'GET',
				'callback'            => static fn () => rest_ensure_response( array() ),
				'permission_callback' => static fn (): bool => current_user_can( Capabilities::VIEW_SUBMISSIONS ),
			)
		);
	}
);

Die vorhandenen Endpunkte listet die REST-API-Referenz.

Frontend ​

ad_form_before_form_render ​

Action · Hooks::BEFORE_FORM_RENDER · FormRenderer::render_form()

php
do_action( 'ad_form_before_form_render', Form $form, array $context ): void
ParameterTypBeschreibung
$formFormZu renderndes Formular
$contextarray<string, mixed>Renderer-Kontext, unter anderem values, errors, success, source und rest_url

ad_form_after_form_render ​

Action · Hooks::AFTER_FORM_RENDER

php
do_action( 'ad_form_after_form_render', Form $form, string $html ): void
ParameterTypBeschreibung
$formFormFormular
$htmlstringErzeugtes Markup

ad_form_rendered_html ​

Filter · Hooks::RENDERED_HTML

php
apply_filters( 'ad_form_rendered_html', string $html, Form $form, array $context ): string
ParameterTypBeschreibung
$htmlstringFertiges Formular-Markup
$formFormFormular
$contextarray<string, mixed>Renderer-Kontext

Der einzige Hook, der die Frontend-Ausgabe tatsächlich verändern kann. Nicht-String-Rückgaben werden verworfen. Wer hier HTML ergänzt, ist selbst für das Escaping verantwortlich.

ad_form_gutenberg_register ​

Action · Hooks::GUTENBERG_REGISTER · GutenbergIntegration::boot()

php
do_action( 'ad_form_gutenberg_register', GutenbergIntegration $integration ): void

Feuert nur, wenn Gutenberg verfügbar ist und der Kern bereits versucht hat, ad-form/form zu registrieren.

ad_form_elementor_register ​

Action · Hooks::ELEMENTOR_REGISTER · ElementorIntegration::register()

php
do_action( 'ad_form_elementor_register', ElementorIntegration $integration ): void

Feuert nur, wenn Elementor geladen ist. Widget- und Kategorie-Registrierung des Kerns sind zu diesem Zeitpunkt bereits eingehängt.

Admin, Logging und Einstellungen ​

Die Admin-Screens selbst bringen keine eigenen Hooks mit – Erweiterungen setzen an den WordPress-Kern-Hooks (admin_menu, admin_enqueue_scripts) und an den folgenden Filtern an.

ad_form_capabilities ​

Filter · Hooks::CAPABILITIES · Capabilities

php
apply_filters( 'ad_form_capabilities', list<string> $caps ): array
ParameterTypBeschreibung
$capslist<string>Die acht Plugin-Capabilities

Standardwerte: manage_ad_form_forms, create_ad_form_forms, edit_ad_form_forms, delete_ad_form_forms, view_ad_form_submissions, edit_ad_form_submissions, delete_ad_form_submissions, manage_ad_form_settings. Sie werden bei der Aktivierung an die Rolle administrator vergeben. Nicht-Array-Rückgaben werden ignoriert.

ad_form_settings ​

Filter · Hooks::SETTINGS · Settings::sanitize()

php
apply_filters( 'ad_form_settings', array $clean, array $data ): array
ParameterTypBeschreibung
$cleanarray<string, mixed>Sanitisierte Einstellungen
$dataarray<string, mixed>Rohe Eingabe

Kern-Schlüssel: delete_data_on_uninstall (bool), store_ip (none | hashed | anonymized | raw), store_user_agent (bool), debug_logging (bool), analytics_enabled (bool). Gespeichert wird unter der Option ad_form_settings.

ad_form_log_context ​

Filter · Hooks::LOG_CONTEXT · Logger::log()

php
apply_filters( 'ad_form_log_context', array $context, string $channel, LogLevel $level ): array
ParameterTypBeschreibung
$contextarray<string, mixed>Kontext nach der Redaction sensibler Schlüssel
$channelstringKanal, z. B. actions, mail, rest
$levelDingfelder\AdForm\Logging\LogLevelEnum-Fall des Log-Levels

Der Logger entfernt vorher selbst Werte zu Schlüsseln wie password, token, secret, authorization, cookie, nonce, iban, api_key. Debug-Einträge werden verworfen, solange die Einstellung debug_logging aus ist. Eine Rückgabe, die kein Array ist, wird zu einem leeren Kontext.

ad_form_integrations ​

Reserviert · Hooks::INTEGRATIONS · wird aktuell nicht ausgelöst.

Übersicht aller Konstanten ​

KonstanteHook-NameTyp
Hooks::LOADEDad_form_loadedAction
Hooks::REGISTER_SERVICESad_form_register_servicesAction
Hooks::SERVICE_PROVIDERSad_form_service_providersFilter
Hooks::REGISTER_MODULESad_form_register_modulesreserviert
Hooks::BEFORE_FORM_RENDERad_form_before_form_renderAction
Hooks::AFTER_FORM_RENDERad_form_after_form_renderAction
Hooks::FIELDSad_form_fieldsFilter
Hooks::REGISTER_FIELDSad_form_register_fieldsAction
Hooks::ACTIONSad_form_actionsFilter
Hooks::MERGE_TAGSad_form_merge_tagsFilter
Hooks::VALIDATION_RULESad_form_validation_rulesreserviert
Hooks::CONDITION_OPERATORSad_form_condition_operatorsFilter
Hooks::INTEGRATIONSad_form_integrationsreserviert
Hooks::REST_ROUTESad_form_rest_routesAction
Hooks::ELEMENTOR_REGISTERad_form_elementor_registerAction
Hooks::GUTENBERG_REGISTERad_form_gutenberg_registerAction
Hooks::SETTINGSad_form_settingsFilter
Hooks::CAPABILITIESad_form_capabilitiesFilter
Hooks::LOG_CONTEXTad_form_log_contextFilter
Hooks::RENDERED_HTMLad_form_rendered_htmlFilter
Hooks::FORM_DEFINITIONad_form_form_definitionFilter
Hooks::FORM_QUERYad_form_form_queryFilter
Hooks::BEFORE_FORM_SAVEad_form_before_form_saveAction
Hooks::AFTER_FORM_SAVEad_form_after_form_saveAction
Hooks::AFTER_FORM_DELETEad_form_after_form_deleteAction
Hooks::FORM_REST_ITEMad_form_form_rest_itemFilter
Hooks::BEFORE_SUBMISSIONad_form_before_submissionAction
Hooks::AFTER_SUBMISSIONad_form_after_submissionAction
Hooks::BEFORE_VALIDATIONad_form_before_validationAction
Hooks::AFTER_VALIDATIONad_form_after_validationAction
Hooks::BEFORE_ACTIONad_form_before_actionAction
Hooks::AFTER_ACTIONad_form_after_actionAction
Hooks::SUBMISSION_QUERYad_form_submission_queryFilter
Hooks::SUBMISSION_REST_ITEMad_form_submission_rest_itemFilter
Hooks::AFTER_ENTRY_STATUSad_form_after_entry_statusAction
Hooks::AFTER_ENTRY_DELETEad_form_after_entry_deleteAction

Die knappe tabellarische Originalfassung steht unter Hooks & Filter (Original).

PHP-Interfaces für Add-ons ​

Diese Interfaces sind als Erweiterungspunkte gedacht und sollten gegenüber konkreten Klassen bevorzugt werden:

  • Dingfelder\AdForm\Core\ServiceProviderInterface
  • Dingfelder\AdForm\Core\ModuleInterface
  • Dingfelder\AdForm\Core\OptionsInterface
  • Dingfelder\AdForm\Forms\FormRepositoryInterface
  • Dingfelder\AdForm\Fields\FieldInterface
  • Dingfelder\AdForm\Actions\ActionInterface
  • Dingfelder\AdForm\Actions\ActionResultInterface
  • Dingfelder\AdForm\Integrations\IntegrationInterface
  • Dingfelder\AdForm\Payments\PaymentGatewayInterface
  • Dingfelder\AdForm\Conditions\ConditionEngineInterface
  • Dingfelder\AdForm\Calculations\CalculationEngineInterface
  • Dingfelder\AdForm\Templates\FormRendererInterface
  • Dingfelder\AdForm\Support\ValidationRuleInterface
  • Dingfelder\AdForm\Logging\LoggerInterface
  • Dingfelder\AdForm\Notifications\MailerInterface
  • Dingfelder\AdForm\Database\DatabaseInterface
  • Dingfelder\AdForm\Database\SchemaInstallerInterface

Digitale Lösungen. Persönlich. Zukunftssicher.

© 2026 Dingfelder Digital · AD Form