Purpose

FieldBag is the runtime wrapper in Cevento that holds a form definition, with optional single-submission payload data.

It combines three responsibilities into one object:

1. Field registry (object graph)

   • It instantiates all field objects for the submitted form (based on the form builder config).
   • It holds those Field instances so you can query and operate on them consistently.

2. Submission data access (normalized + raw)

   • It stores the incoming request payload (field_key => field_value) as raw input.
   • It provides a filtered/normalized representation of that data for processing and persistence.

3. Validation + error aggregation

   • It triggers validation for each field after the submission.
   • It collects field-specific and global errors in a structure the frontend can render.

The result: validation hooks and business logic can work with field objects instead of dealing with raw $_POST arrays and form schema details.

Usage Patterns

Field-level custom validation

Operate on Field objects instead of handling $_POST data directly:

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

    if (strlen($nameValue) addError('Name must be at least 3 characters long.');
    }

    $fieldBag->addGlobalError('A global error message can be placed here.');
}, 10, 2);

Query fields by type

Useful for repeatable groups like participants.

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

Read normalized vs raw submission data

• getDataRaw() gives you exact stored submission data
• getData() returns filtered/normalized data:
  • performs field-specific sanitization
  • removes honeypot field keys
  • normalizes checkbox 'on' into the configured value (general.value)

Use getData() for business logic and persistence. Use getDataRaw() for debugging or low-level inspection.

API Reference

Static Factory

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

Creates a FieldBag using an event’s booking form configuration.

Parameters

• $event: the event array of the current context
• $data: submission payload (optional, defaults to an empty array)

Returns

• FieldBag with all field instances created and optionally populated with submission data.

Field Lookup

getField(string $key)

Returns a Field instance by:

• field key if $key starts with field_
• otherwise field label match

Returns

• Field|null

hasField(string $fieldKey): bool

Checks whether a field key exists in the current bag.

getFields(): array

Returns all top-level fields that are currently registered.

getAllFields(): array

Returns every registered field instance, including nested/child fields.

getFieldsByType(string $type): array

Returns all registered field of a specific field type.

Data Access

getData(): array

Returns normalized submission data as associative array of field_key => value pairs:

getDataRaw(): array

Returns $this->data exactly as currently stored/submitted.

Validation

addGlobalError(string $message): void

Adds a global error message, typically rendered above the form.

hasErrors(): bool

Returns true if any field or global errors exist.

Return type is effectively bool.

getErrors(): array

Returns the complete error payload:

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

Built-in Helpers

getTotalParticipants(): int

Counts total participants across all participants_group fields. If no participant group exists, returns 0

getParticipants(): array

Flattens participants across all participants_group fields into a single array.

Behavioral Details and Edge Cases

getField() can return null

If no field matches the provided key or label, getField() returns null. Always check for null before using the returned value.

Checkbox normalization

getData() treats checkbox submissions where value is 'on' as “checked” and replaces 'on' with the configured “general.value”. This makes downstream logic stable even if the browser submits 'on'. If there is no value in the current submission, the checkbox is considered “unchecked” and null is beeing returned.

Parent/child field handling

getFields() filters out fields that have a parent state. This implies:

• validation iteration runs only on top-level fields
• child fields are validated indirectly by their parent field type