Fluent Form Builder

Build forms programmatically using Polyform's fluent API for complete control over form structure and configuration.

Overview

The FormBuilder class provides a fluent, expressive API for creating forms programmatically. This is ideal for seeding databases, creating forms in migrations or building forms dynamically based on application logic.

When to use FormBuilder

Use the fluent builder when creating forms programmatically in code. For user-facing form creation, use the drag-and-drop form builder UI component.

Getting Started

Start building a form using the Polyform facade or by instantiating FormBuilder directly. Every form must be associated with a "formable" model.

Creating a Form Builder

Form Configuration

Configure form-level settings using chainable methods. Only name() is required; all other settings are optional.

Form Configuration Example

Configuration Methods

Method	Description
`name(string $name)`	Set the form name (required)
`slug(?string $slug)`	Set URL-friendly slug (auto-generated if omitted)
`description(?string $description)`	Set form description
`maxSubmissions(?int $max)`	Limit total submissions
`opensAt($datetime)`	Set opening date/time
`closesAt($datetime)`	Set closing date/time
`allowEditAfterSubmit(bool $allow)`	Allow users to edit submissions
`allowMultipleSubmissions(bool $allow)`	Allow multiple submissions per user
`confirmationMessage(?string $message)`	Message shown after submission
`redirectUrl(?string $url)`	Redirect after submission
`notifyEmails(array $emails)`	Email addresses to notify on submission
`settings(array $settings)`	Custom settings array
`metadata(array $metadata)`	Custom metadata array
`fromTemplate(Form $template)`	Copy structure from existing form
`addStep(string $title, ?string $desc, ?string $icon)`	Add a new step (multi-step forms)
`addField(FieldType $type, string $key, string $label, array $options)`	Add field with full control
`build()`	Save form and return Form model

Multi-Step Forms

Create multi-step forms using addStep(). Fields added after a step are automatically assigned to that step until the next addStep() call.

Multi-Step Form

Step icons

The icon parameter accepts any icon identifier supported by your frontend icon library. Common choices: 'user', 'settings', 'message', 'briefcase', 'clipboard'.

Adding Fields

Polyform provides 26+ convenience methods for adding fields. Each method returns a field configurator for chainable field-level settings.

All Field Methods

Method	Description
`addText(string $key, string $label)`	Single-line text input
`addTextarea(string $key, string $label)`	Multi-line text area
`addRichText(string $key, string $label)`	WYSIWYG editor
`addNumber(string $key, string $label)`	Numeric input
`addEmail(string $key, string $label)`	Email input with validation
`addSelect(string $key, string $label)`	Single-select dropdown
`addSelectFromEnum(string $key, string $label, string $enumClass)`	Select from enum cases
`addSelectFromModel(string $key, string $label, string $modelClass)`	Select from database model
`addSelectFromResolver(string $key, string $label, string $resolver)`	Select with custom resolver
`addMultiSelect(string $key, string $label)`	Multi-select dropdown
`addRadio(string $key, string $label)`	Radio button group
`addCheckboxGroup(string $key, string $label)`	Checkbox group
`addCheckbox(string $key, string $label)`	Single checkbox
`addToggle(string $key, string $label)`	Toggle switch
`addFile(string $key, string $label)`	Single file upload
`addMultiFile(string $key, string $label)`	Multiple file upload
`addImage(string $key, string $label)`	Image upload
`addSignature(string $key, string $label)`	Signature pad
`addRating(string $key, string $label)`	Star rating
`addScale(string $key, string $label)`	Numeric scale (e.g., 1-10)
`addDate(string $key, string $label)`	Date picker
`addDateTime(string $key, string $label)`	Date and time picker
`addHidden(string $key)`	Hidden field
`addSectionBreak(string $label)`	Visual divider
`addHeading(string $label, string $level)`	Section heading
`addRepeater(string $key, string $label)`	Repeatable field group
`addMatrix(string $key, string $label)`	Matrix/grid input

Text Fields

Text Field Examples

Select Fields

Select Field Examples

Dynamic options

Use addSelectFromEnum(), addSelectFromModel() or addSelectFromResolver() for dynamic option sources. See the Option Sources documentation for details.

Choice Fields

Choice Field Examples

File Upload Fields

File Upload Examples

Rating & Scale Fields

Rating Field Examples

Date Fields

Date Field Examples

Other Fields

Other Field Types

Generic addField() Method

For complete control or custom field types, use the generic addField() method. This accepts any field option, including conditional logic and custom validation rules.

Generic addField()

Creating from Templates

Duplicate an existing form's structure using fromTemplate(). This copies all fields, steps and settings while allowing you to override specific properties.

Template Example

Comprehensive Example

A complete multi-step conference registration form demonstrating most features:

Complete Conference Registration Form

Building the Form

Call build() to persist the form and its fields to the database. This method returns the created Form model instance.

Transaction recommended

The build() method creates multiple database records (Form, FormSteps, FormFields). Consider wrapping it in a database transaction if you need atomic form creation.

Layout Fields Validation