crewli/dev-docs/form-builder-getting-started.md

Form Builder — Developer Getting Started

Onboarding for developers writing code against the new form-builder tables. Companion to /dev-docs/ARCH-FORM-BUILDER.md v1.2 (the authoritative spec) and /dev-docs/SCHEMA.md §3.5.12.

---

Prerequisites

• Laravel 12 / PHP 8.2+.
• Familiarity with Eloquent, ULIDs, polymorphic relationships.
• Read ARCH §0 (TL;DR) and §3 (FormPurpose catalogue).

---

The mental model in one paragraph

A FormSchema is a form definition. FormFields belong to it. A FormSubmission is one filled-in instance of a schema, identified by its polymorphic subject (a Person, User, Company, Organisation, Event, or nothing for public forms). FormValues are the EAV row per (submission, field) pair, JSON payload + typed columns populated by an observer based on the field's storage hint and filterability. Every schema declares its purpose (event_registration, incident_report, …) which constrains lifecycle and integrations.

---

Creating a new schema with two fields

use App\Enums\FormBuilder\FormFieldType;
use App\Enums\FormBuilder\FormPurpose;
use App\Enums\FormBuilder\FormSubmissionMode;
use App\Models\Event;
use App\Models\FormBuilder\FormField;
use App\Models\FormBuilder\FormSchema;

$event = Event::find($eventId);

$schema = FormSchema::create([
    'organisation_id' => $event->organisation_id,
    'owner_type' => 'event',
    'owner_id' => $event->id,
    'name' => "{$event->name} — registratie",
    'slug' => "{$event->slug}-registratie",
    'purpose' => FormPurpose::EVENT_REGISTRATION,
    'submission_mode' => FormSubmissionMode::DRAFT_SINGLE,
    'is_published' => false,
    'locale' => 'nl',
]);

FormField::create([
    'form_schema_id' => $schema->id,
    'field_type' => FormFieldType::SELECT->value,
    'slug' => 'shirtmaat',
    'label' => 'Shirtmaat',
    'options' => ['XS', 'S', 'M', 'L', 'XL', 'XXL'],
    'is_required' => true,
    'is_filterable' => true,
    'value_storage_hint' => FormFieldType::SELECT->recommendedValueStorageHint(),
    'sort_order' => 1,
]);

FormField::create([
    'form_schema_id' => $schema->id,
    'field_type' => FormFieldType::TEXTAREA->value,
    'slug' => 'opmerkingen',
    'label' => 'Opmerkingen',
    'value_storage_hint' => FormFieldType::TEXTAREA->recommendedValueStorageHint(),
    'sort_order' => 2,
]);

Then to log a meaningful change:

$schema->is_published = true;
$schema->save();
$schema->logSchemaChange('schema.published');

Trivial label/help_text edits should NOT call logSchemaChange — see ARCH §17.1 for the curated event list.

---

Creating a submission and its values

use App\Enums\FormBuilder\FormSubmissionStatus;
use App\Models\FormBuilder\FormSubmission;
use App\Models\FormBuilder\FormValue;

$person = \App\Models\Person::find($personId);

$submission = FormSubmission::create([
    'form_schema_id' => $schema->id,
    'subject_type' => 'person',
    'subject_id' => $person->id,
    'submitted_by_user_id' => $person->user_id,
    'status' => FormSubmissionStatus::SUBMITTED,
    'submitted_at' => now(),
    'is_test' => false,
]);

// One value per field. The shape of `value` is JSON-wrapped per field type.
FormValue::create([
    'form_submission_id' => $submission->id,
    'form_field_id' => $shirtmaatField->id,
    'value' => ['value' => 'L'],
]);

FormValue::create([
    'form_submission_id' => $submission->id,
    'form_field_id' => $opmerkingenField->id,
    'value' => ['value' => 'Graag een nachtshift'],
]);

FormValueObserver automatically populates value_indexed for filterable single-value fields, value_number for NUMBER hint, value_date for DATE hint, value_bool for BOOL hint, and the form_value_options pivot for multi-value filterable fields (MULTISELECT / CHECKBOX_LIST / TAG_PICKER). You don't write to those columns directly.

---

Adding a new subject type

Three places to update — keep them in sync:

1. Morph map (app/Providers/AppServiceProvider.php):

   Relation::enforceMorphMap([
       // …existing entries…
       'artist' => \App\Models\Artist::class,
   ]);
   

2. Subject registry (config/form_subjects.php):

   'artist' => [
       'model' => \App\Models\Artist::class,
       'display_attribute' => 'name',
       'permission_check' => \App\Policies\ArtistPolicy::class.'@view',
   ],
   

3. Reverse relation on the model itself:

   public function formSubmissions(): MorphMany
   {
       return $this->morphMany(\App\Models\FormBuilder\FormSubmission::class, 'subject');
   }
   

The verifier (forms:verify-data-integrity) cross-checks subject_type against the config/form_subjects.php keys; an unknown subject_type will fail the submission-coherence check.

---

Registering a custom field type

The field_type column on form_fields is a string, not a DB enum, so custom types can be added at runtime via configuration. Under the hood this is the CustomFieldTypeRegistry planned for ARCH §17.2 — for now, register the type's value in config/form_builder.php:

'custom_field_types' => [
    'COLOR_PICKER' => [
        'label' => 'Kleurkeuze',
        'storage_hint' => 'string',
        'filterable' => true,
    ],
],

The verifier accepts any field_type that's either in FormFieldType::values() or in config('form_builder.custom_field_types'). Frontend rendering and validation handlers come in S6 when the registry interface lands.

---

Suppressing activity log during bulk operations

logSchemaChange and logFieldChange produce one activity-log row per call. In bulk fixture runs (DevSeeder, the data-migration command, import scripts) this floods activity_log with hundreds of rows that provide no audit value. Wrap the bulk operation:

use App\Support\ActivityLog;

ActivityLog::suppressed(function () use ($schemas): void {
    foreach ($schemas as $schemaData) {
        $schema = FormSchema::create($schemaData);
        // logSchemaChange calls inside this closure are silent no-ops.
    }
});

The helper flips config('activitylog.enabled') for the duration of the callback and restores it in finally. Both our explicit calls AND the spatie LogsActivity trait (used on Organisation elsewhere) respect the flag via ActivityLogger::log().

Do NOT use this in regular request paths — the activity log is the audit trail; suppressing it silently is an antipattern outside of fixtures and one-shot commands.

---

Where to look next

• ARCH-FORM-BUILDER.md §4 — full column specs for every table.
• ARCH-FORM-BUILDER.md §6 — binding patterns (entity-owned / form-owned / mirrored).
• ARCH-FORM-BUILDER.md §7 — filter architecture and the FilterQueryBuilder interface (S4).
• config/form_binding.php — Entity Column Registry (Pattern A/C binding targets).
• config/form_subjects.php — Subject Type Registry.
• config/form_builder.php — limits, webhook policy, captcha, retention, feature flags.
• forms:migrate-legacy-data + forms:verify-data-integrity — see the migration playbook in this directory for the operator's view.