Form Builder

Form Builder

FormBuilder adds form definitions, encrypted submissions, frontend Livewire rendering, conditional logic, multi-step forms, calculations, file upload rules, spam scoring, payment fields, and submission workflows to Capell.

At A Glance

• Package: capell-app/form-builder
• Namespace: Capell\FormBuilder\
• Surfaces: Filament admin resource, frontend Livewire, database
• Service providers: packages/form-builder/src/Providers/FormBuilderServiceProvider.php
• Capell dependencies: capell-app/admin, capell-app/core, capell-app/frontend

Why It Helps Your Capell Workflow

• Lets editors build and publish forms while the package owns encrypted submissions, validation, notifications, and status handling.
• Helps owners collect leads, enquiries, and operational requests without custom Livewire work for every form.
• Gives developers a predictable form/submission model that can connect to Public Actions, Email Studio, and campaign workflows.

Best Used With

• Public Actions
• Email Studio
• Campaign Studio

What It Adds

FormBuilder adds form definitions, encrypted submissions, frontend Livewire rendering, conditional logic, multi-step forms, calculations, file upload rules, spam scoring, payment fields, and submission workflows to Capell.

• Form and submission models.
• Admin submissions resource under the reports navigation group.
• Frontend Livewire form component.
• Actions for validation, conditional visibility, multi-step grouping, calculations, spam scoring, submission creation, archiving, read state, and spam marking.
• FormSubmitted event.
• Configurable submission storage, request metadata collection, file upload rules, payment field metadata, notifications, and replies.

Why It Matters

For developers: Keeps form schema, settings, submission payload, and metadata in data objects and casts so form handling remains typed across layers.

For teams: Lets editors collect responses from structured websites while keeping submission review inside the Capell admin workflow.

Built With

This package makes its Composer dependencies visible because they are part of the value proposition, not just plumbing. When an upstream package has a public repository, its linked preview card points readers back to the maintainers so their work gets proper credit.

Capell packages used here

• Capell Admin
• Capell Core
• Capell Frontend

Open-source packages used here

• No extra third-party Composer package beyond the Capell package stack is required here.

Screens And Workflow

Screenshots are generated from docs/screenshots.json during package deployment.

• FormBuilder admin index.
• Create/edit form schema screen.
• Submissions index.
• Frontend form output.
• Submission detail view.

Technical Shape

• FormBuilderServiceProvider registers the package.
• Config file: capell-form-builder.php.
• Migrations create form-builder and submissions.
• Models: Form and Submission.
• Livewire component: FormComponent.
• EncryptedDataCast protects stored submission data.

Code Map

Runtime Surface

• Livewire: FormComponent.

Data And Persistence

• form-builder belongs to sites and stores handle, schema, settings, and active state.

• submissions belongs to form-builder and sites and stores payload, meta, status, and submitted_at.

• Submission payload and metadata are represented by data objects.

• Deletion and retention rules should be verified against the host application policy.

• Models: Form, Submission.

• Migrations: 2026_05_10_190849_01_create_form-builder_table.php, 2026_05_10_190849_02_create_submissions_table.php.

• Config: packages/form-builder/config/capell-form-builder.php.

• Data objects live in src/Data/; use them for payloads, form state, and view models.

Extension Points

• Events: FormSubmitted.
• Register Capell extension points, routes, migrations, settings, render hooks, and resources from service providers.

Install Impact

• Adds form-builder and submissions tables.
• Adds frontend Livewire form component.
• Adds config keys for storing submissions, IP address collection, user agent collection, throttling, and spam scoring.
• No routes are visible in this package.

Install And Setup

• Install with composer require capell-app/form-builder in the host Capell application.
• Run migrations through the host application package install flow.
• In this repository, verify package changes with vendor/bin/pest; do not use php artisan.

Admin And Access

• Admin resource: SubmissionResource.
• Navigation: Form submissions under the reports group.
• Access is governed by SubmissionPolicy and site-scoped submission queries.

Common Pitfalls

• Disable IP/user agent collection where privacy policy requires it.
• Run migrations before rendering form components.
• Validate field schema before accepting public submissions.
• Tune spam scoring thresholds and blocked keywords for the site’s risk profile before using automatic spam triage in production.

Docs

• docs index
• credits-and-acknowledgements.md
• overview.md

Testing

Run package tests from the repository root:

vendor/bin/pest packages/form-builder/tests --configuration=phpunit.xml

Maintenance Notes

• Treat public routes as untrusted input and keep validation, permission checks, and side effects inside actions or dedicated services.
• Put behaviour changes in src/Actions/; UI classes, commands, and controllers should call actions instead of owning domain logic.
• Use package Data classes at boundaries instead of passing anonymous arrays between layers.
• Use backed enums for persisted values and enum labels for Filament options.

FormBuilder

Status: Available, schema-owning · Kind: package · Tier: premium · Bundle: form-builder · Contexts: admin, frontend · Product group: Capell FormBuilder

This page is the consolidated implementation overview for the FormBuilder package. It is extracted from the package README, service providers, migrations, config files, routes, resources, models, actions, and the shared Capell ERD notes where available.

What This Package Adds

FormBuilder adds form definitions, encrypted submissions, frontend Livewire rendering, conditional logic, multi-step forms, calculations, file upload rules, spam scoring, payment fields, and submission workflows to Capell.

• Form and submission models.
• Frontend Livewire form component.
• Actions for validation, conditional visibility, multi-step grouping, calculations, spam scoring, submission creation, archiving, read state, and spam marking.
• FormSubmitted event.
• Configurable submission storage, request metadata collection, file upload rules, payment field metadata, notifications, and replies.

Developer Notes

Keeps form schema, settings, submission payload, and metadata in data objects and casts so form handling remains typed across layers.

• FormBuilderServiceProvider registers the package.
• Config file: capell-form-builder.php.
• Migrations create form-builder and submissions.
• Models: Form and Submission.
• Livewire component: FormComponent.
• EncryptedDataCast protects stored submission data.

Operational Notes

Lets editors collect responses from structured websites while keeping submission review inside the Capell admin workflow.

• Adds form-builder and submissions tables.
• Adds frontend Livewire form component.
• Adds config keys for storing submissions, IP address collection, user agent collection, throttling, and spam scoring.
• No routes are visible in this package.

Data And Retention

• form-builder belongs to sites and stores handle, schema, settings, and active state.
• submissions belongs to form-builder and sites and stores payload, meta, status, and submitted_at.
• Submission payload and metadata are represented by data objects.
• Deletion and retention rules should be verified against the host application policy.

Screenshot Plan

• FormBuilder admin index.
• Create/edit form schema screen.
• Submissions index.
• Frontend form output.
• Submission detail view.

Screenshots

The existing screenshot captures are retained as runner evidence only. They currently show Form Mappings rather than Form Builder schema, submissions, detail, or frontend output, so marketplace media keeps only the extension card until recapture.

The frontend and submission detail screenshots need seeded form definitions and submissions before they can represent the package accurately. Do not publish blank frontend captures for those states.

Pitfalls

• Disable IP/user agent collection where privacy policy requires it.
• Run migrations before rendering form components.
• Validate field schema before accepting public submissions.
• Tune spam scoring thresholds and blocked keywords for the site’s risk profile before using automatic spam triage in production.

Verification

• Run vendor/bin/pest packages/form-builder/tests when package tests exist.
• Run the relevant host-app migration or package install flow in a disposable database.
• Open the listed admin or frontend surface and compare it with the screenshot plan.

Package Manifest

• Composer name: capell-app/form-builder
• Product group: Capell FormBuilder
• Kind: package
• Tier: premium
• Bundle: form-builder
• Contexts: admin, frontend
• Requires: capell-app/core, capell-app/admin, capell-app/frontend
• Optional dependencies: None listed.

Admin Surfaces

• Resource: SubmissionResource.
• Page: ListSubmissions.
• Navigation: Form submissions under the reports group.
• Table actions include read, archive, spam, reply, and payload review states.

Commands

• None proven in this package directory.

Routes And Config

• Config: packages/form-builder/config/capell-form-builder.php

Permissions And Gates

• None proven in this package directory.

Migrations

• Migration: create_form-builder_table.php
• Migration: create_submissions_table.php

ERD Excerpt

erDiagram
    SITES ||--o{ FORMS : owns
    FORMS ||--o{ SUBMISSIONS : receives
    SITES ||--o{ SUBMISSIONS : scopes

    FORMS {
        bigint id PK
        bigint site_id FK
        string handle
        json schema
        json settings
        boolean is_active
    }

    SUBMISSIONS {
        bigint id PK
        bigint form_id FK
        bigint site_id FK
        longtext payload
        longtext meta
        string status
        timestamp submitted_at
    }

Screenshot Automation

Deployment should read screenshots.json, install the package with demo data, resolve each admin surface or frontend URL, and write images to packages/form-builder/docs/screenshots.

• FormBuilder admin index.
• Create/edit form schema screen.
• Submissions index.
• Frontend form output.
• Submission detail view.