Entwicklungs-Workflow

Befehle im Überblick

Befehl	Zweck
npm start	wp-scripts start – Watch-Modus für Builder und Block, schreibt nach assets/build/
npm run build	Produktions-Build der Assets plus Erzeugung von assets/build/index.php
npm run lint:js	ESLint über assets/src (wp-scripts lint-js)
composer test	PHPUnit über die Test-Suite Unit
vendor/bin/phpcs	WordPress Coding Standards prüfen
vendor/bin/phpcbf	Automatisch behebbare Coding-Standard-Verstöße korrigieren

composer test, composer phpcs und composer phpcbf sind Aliase, die in der composer.json unter scripts definiert sind.

Asset-Entwicklung

npm start

Der Watch-Modus baut die beiden Entry-Points aus webpack.config.js:

• builder → assets/src/builder/index.tsx
• block → assets/src/block/index.tsx

Ausgabeverzeichnis ist assets/build/. Die Konfiguration erweitert die Standard-Config von @wordpress/scripts an einer Stelle: react/jsx-runtime und react/jsx-dev-runtime werden gebündelt statt als WordPress-Script-Handle externalisiert, weil WordPress 6.4 und 6.5 das Handle react-jsx-runtime noch nicht registrieren.

Gebaute Assets nicht von Hand bearbeiten

assets/build/ ist Build-Output. Änderungen gehören immer nach assets/src/.

Tests

composer test

Die Suite läuft ohne WordPress-Installation. tests/bootstrap.php stellt die benötigten WordPress-Funktionen bereit, und tests/Support/ enthält die Test-Doubles, die an Stelle der echten Infrastruktur in den Container gehängt werden:

Double	Ersetzt
InMemoryDatabase	DatabaseInterface / wpdb
InMemoryOptions	OptionsInterface / Options-API
CapturingMailer	MailerInterface / wp_mail()
CapturingLogger	LoggerInterface
CapturingInstaller	SchemaInstallerInterface / dbDelta()
FakeLicenseTransport	ApiTransportInterface / wp_remote_post()
LicensePayloadFactory / LicenseSigner	Signierte Test-Payloads (Ed25519)

Die Konfiguration steht in phpunit.xml.dist: Bootstrap tests/bootstrap.php, Suite Unit aus tests/Unit, Coverage-Quelle src. failOnRisky und failOnWarning sind aktiv – ein Test, der nur Warnungen erzeugt, gilt als Fehlschlag.

Einzelne Tests laufen direkt über PHPUnit:

vendor/bin/phpunit --filter ContainerTest
vendor/bin/phpunit tests/Unit/Fields

Namespace der Tests ist Dingfelder\AdForm\Tests\ (siehe autoload-dev in der composer.json), die Verzeichnisstruktur unter tests/Unit/ spiegelt src/.

Coding Standards

vendor/bin/phpcs          # prüfen
vendor/bin/phpcbf         # automatisch korrigieren
vendor/bin/phpcs src/Fields/AbstractField.php   # einzelne Datei

Geprüft werden ad-form.php, uninstall.php, src/, templates/ und tests/. Die genauen Regeln stehen unter Coding Conventions.

Verzeichnisstruktur

ad-form/
├── ad-form.php            Plugin-Header, Konstanten, PHP-Check, Autoloader, Boot-Hook
├── uninstall.php          Aufräumen bei Deinstallation (respektiert die Datenschutz-Einstellung)
├── composer.json          PSR-4-Autoload, Dev-Tools, Scripts
├── package.json           Asset-Build (@wordpress/scripts)
├── webpack.config.js      Entry-Points builder + block
├── phpcs.xml.dist         WordPress Coding Standards
├── phpunit.xml.dist       Test-Suite Unit
├── src/                   Produktionscode (PSR-4: Dingfelder\AdForm\)
├── assets/                Frontend- und Admin-Assets
├── templates/             PHP-Templates der Admin-Screens
├── tests/                 PHPUnit-Suite und Test-Doubles
├── languages/             Übersetzungen (Textdomain ad-form)
├── docs/                  Referenzdokumente (Quelle dieser Site)
└── dev-docs/              Diese VitePress-Site

src/ im Detail

src/ ist nach Domänen geschnitten. Jedes Verzeichnis mit eigenem Bootstrapping enthält einen Service Provider.

Verzeichnis	Inhalt
Core/	Container, Hooks-Konstanten, PluginInfo, Settings, Options, Activator/Deactivator/Uninstaller
Database/	wpdb-Adapter, Tabellennamen, Schema, Migrator, Stats
Forms/	Form-Entity, Repository, FormService, Definition-Sanitizing, JSON-Schema
Fields/	FieldInterface, AbstractField, FieldRegistry, Fields/Types/*
Conditions/	ConditionEngine für Show/Hide- und Action-Regeln
Calculations/	CalculationEngine – rekursiv absteigender Parser ohne eval()
Actions/	ActionInterface, AbstractAction, Registry, Runner, MergeTagEngine, Types/EmailAction
Submissions/	SubmitService, SubmissionService, Repository, Query- und Status-Objekte
Frontend/	Shortcode, FormRenderer, SubmitListener, bedingtes Asset-Enqueue
Admin/	Menü, Forms- und Entries-Screens, Admin-Assets
REST/	Controller für ad-form/v1 plus Permissions
Gutenberg/ , Elementor/	Optionale Editor-Integrationen
Steps/	StepEngine für Multi-Step-Formulare
Security/	Capabilities, Nonce, Sanitizer
Logging/ , Notifications/	Logger mit Redaction, Mailer-Abstraktion
Licensing/	License API Client, Signatur, Cache, Scheduler, Entitlements, Save-/Runtime-Gates, License-Admin
Integrations/ , Payments/ , Templates/ , Support/	Interfaces und Helfer

assets/src/

assets/src/
├── builder/     React-Builder (App.tsx, components/, api.ts, fields.ts, steps.ts, history.ts …)
└── block/       Gutenberg-Block ad-form/form (index.tsx, edit.tsx, types.ts)

Nicht kompilierte Assets, die direkt ausgeliefert werden, liegen daneben: assets/frontend/ (form.css, form.js), assets/admin/ und assets/elementor/.

templates/

PHP-Templates der Admin-Screens, gerendert über Dingfelder\AdForm\Admin\View. Erlaubt sind ausschließlich die in View::TEMPLATES gelisteten Namen – ein unbekannter Name wirft eine RuntimeException:

templates/admin/
├── dashboard.php
├── forms.php
├── form-edit.php     Mount-Punkt #ad-form-builder für den React-Builder
├── entries.php
├── entry-detail.php
├── license.php       Lizenz verbinden, Status, Featureübersicht
└── settings.php

Debugging

Der Logger schreibt kanalbasiert in eine eigene Tabelle und redigiert Kontextdaten, bevor sie gespeichert werden. Debug-Logging wird über die Plugin-Einstellung debug_logging aktiviert. Der Kontext lässt sich vor dem Schreiben noch einmal über ad_form_log_context filtern – siehe Hook-Referenz.

Entwickler-Dokumentation veröffentlichen

Die VitePress-Site unter dev-docs/ wird nach https://adforms.docs.andredingfelder.com ausgeliefert. Build und Sync:

cd dev-docs
npm ci
npm run build

Das Verzeichnis dev-docs/.vitepress/dist gehört nach /home/u374543/ad-form-dev-docs auf dem VPS. Nginx-Vorlage: dev-docs/deploy/adforms-docs-andredingfelder-com.conf. Der Container server-stack-nginx-1 mountet dieses Verzeichnis nach /var/www/ad-form-docs. Nach einem neuen Volume-Eintrag in der Compose-Datei nur den Nginx-Service neu erzeugen, nicht den gesamten Stack.

Die Statusseite unter https://adforms.docs.andredingfelder.com/status/ ist Gatus (dev-docs/deploy/gatus/config.yaml). Der Container hängt im server-stack am Netz proxy; Nginx legt den Prefx /status/ davor.