Zweck

FieldBag ist eine Klasse in Cevento, die eine Formular-Definition hält, optional inklusive Payload-Daten einer einzelnen Buchung.

Sie vereint drei Verantwortlichkeiten in einem Objekt:

1. Feld-Registry (Objektgraph)

   • Sie instanziiert alle Feldobjekte für das eingereichte Formular (basierend auf der Form-Builder-Konfiguration).
   • Sie hält diese Field-Instanzen, sodass du sie konsistent abfragen und mit ihnen arbeiten kannst.

2. Zugriff auf Buchungs-Daten (normalisiert & auch als Rohdaten)

   • Sie speichert die eingehende Request-Payload (field_key => field_value) als Roh-Input.
   • Sie stellt eine gefilterte/normalisierte Repräsentation dieser Daten für Verarbeitung und Persistenz bereit.

3. Validierung + Fehleraggregation

   • Sie stößt nach der Buchung die Validierung für jedes Feld an.
   • Sie sammelt feldspezifische und globale Fehler in einer Struktur, die das Frontend rendern kann.

Ergebnis: Validierungs-Hooks und Business-Logik können mit Feldobjekten arbeiten, statt sich mit rohen $_POST-Arrays und Formularschema-Details zu befassen.

Nutzungsmuster

Feldbezogene benutzerdefinierte Validierung

Arbeite mit Field-Objekten, statt $_POST-Daten direkt zu verarbeiten:

add_action('cevento/validate', function ($fieldBag, $event) {
    $nameField = $fieldBag->getField('Name');   // Lookup per Label
    $nameValue = $nameField->getValue();

    if (strlen($nameValue) addError('Name muss mindestens 3 Zeichen lang sein.');
    }

    $fieldBag->addGlobalError('Eine globale Fehlermeldung kann hier gesetzt werden.');
}, 10, 2);

Felder nach Typ abfragen

Nützlich für wiederholbare Gruppen wie Teilnehmende.

$participantGroups = $fieldBag->getFieldsByType('participants_group');
foreach ($participantGroups as $groupField) {
    $values = $groupField->getValue(); // meist ein Array
}

Normalisierte vs. rohe Buchungs-Daten lesen

• getDataRaw() liefert dir die exakt gespeicherten Buchungs-Daten
• getData() liefert gefilterte/normalisierte Daten:
  • führt feldspezifische Sanitization durch
  • entfernt Honeypot-Feld-Keys
  • normalisiert Checkbox 'on' auf den konfigurierten Wert (general.value)

Nutze getData() für Business-Logik und Persistenz. Nutze getDataRaw() für Debugging oder Low-Level-Inspektion.

API-Referenz

Statische Factory

FieldBag::fromEvent(array $event, array $data = []): FieldBag

Erzeugt einen FieldBag anhand der Buchungsformular-Konfiguration eines Events.

Parameter

• $event: das Event-Array des aktuellen Kontexts
• $data: Buchungs-Payload (optional, Standard ist ein leeres Array)

Rückgabe

• FieldBag mit allen erzeugten Field-Instanzen, optional mit Buchungs-Daten befüllt.

Field-Lookup

getField(string $key)

Gibt eine Field-Instanz zurück anhand:

• Des Field-Keys, wenn $key mit field_ beginnt
• Einer Übereinstimmung des Field-Labels

Rückgabe

• Field|null

hasField(string $fieldKey): bool

Prüft, ob ein Field-Key im aktuellen Bag existiert.

getFields(): array

Gibt alle aktuell registrierten Top-Level-Felder zurück.

getAllFields(): array

Gibt jede registrierte Field-Instanz zurück, inklusive verschachtelter/Child-Felder.

getFieldsByType(string $type): array

Gibt alle registrierten Felder eines bestimmten Field-Typs zurück.

Datenzugriff

getData(): array

Gibt normalisierte Buchungs-Daten als assoziatives Array von field_key => value zurück:

getDataRaw(): array

Gibt $this->data exakt so zurück, wie es aktuell gespeichert/eingereicht wurde.

Validierung

addGlobalError(string $message): void

Fügt eine globale Fehlermeldung hinzu, die typischerweise oberhalb des Formulars gerendert wird.

hasErrors(): bool

Gibt true zurück, wenn feldbezogene oder globale Fehler vorhanden sind.

Der Rückgabetyp ist effektiv bool.

getErrors(): array

Gibt die vollständige Fehler-Payload zurück:

[
  'fields' => [ 'field_key' => ['msg1', 'msg2'], ... ],
  'global' => ['msg1', 'msg2', ...]
]

Eingebaute Helper

getTotalParticipants(): int

Zählt die Gesamtzahl der Teilnehmenden über alle participants_group-Felder. Wenn keine Participant-Group existiert, wird 0 zurückgegeben.

getParticipants(): array

Flattened alle Teilnehmenden über alle participants_group-Felder in ein einzelnes Array.

Verhaltensdetails und Edge Cases

getField() kann null zurückgeben

Wenn kein Feld zum übergebenen Key oder Label passt, gibt getField() null zurück. Vor der Verwendung immer auf null prüfen.

Checkbox-Normalisierung

getData() behandelt Checkbox Werte mit dem Wert 'on' als „checked“ und ersetzt 'on' durch den konfigurierten Wert (general.value). Das stabilisiert nachgelagerte Logik, selbst wenn der Browser 'on' sendet. Wenn in der aktuellen Buchung kein Wert vorhanden ist, gilt die Checkbox als „unchecked“ und es wird null zurückgegeben.

Parent/Child-Field-Handling

getFields() filtert Felder heraus, die ein Eltern-Feld haben. Das impliziert:

• die Validierungsiteration läuft nur über Top-Level-Felder
• Child-Felder werden indirekt über ihren Parent-Field-Typ validiert