Multi-Step Forms with FormBuilder

Purpose and Scope

This document covers the FormBuilder system, which enables creation of complex, multi-step CLI forms with conditional logic, backward navigation, and sequential prompt orchestration. The FormBuilder combines multiple interactive prompts into a single cohesive workflow where users can navigate forward and backward through steps, with each step having access to responses from previous steps.

For information about individual prompt types that can be used within forms, see Interactive Prompts. For display components, see Display Components.

---

Overview

The FormBuilder system orchestrates sequences of prompts and display components into wizard-like experiences. Users interact with one prompt at a time, can navigate backward to change previous answers, and the form maintains state across all steps. The system is built on three core classes:

Class	Purpose	File Path
FormBuilder	Orchestrates steps, manages responses, handles navigation	src/FormBuilder.php
FormStep	Encapsulates individual step logic and conditions	src/FormStep.php
FormRevertedException	Signals backward navigation requests	src/Exceptions/FormRevertedException.php

The entry point is the form() helper function at src/helpers.php256-261

Sources: src/FormBuilder.php src/helpers.php256-261 src/FormStep.php src/Exceptions/FormRevertedException.php

---

System Architecture

Sources: src/FormBuilder.php src/FormStep.php src/Exceptions/FormRevertedException.php src/helpers.php256-261

---

Creating a Form

Forms are created using the form() helper function, which returns a FormBuilder instance. Steps are added using method chaining, and the form is executed by calling submit().

Basic structure:

The submit() method executes all steps sequentially and returns an array of responses keyed by step names (or numeric indices if names are not provided).

Sources: src/helpers.php256-261 src/FormBuilder.php52-88

---

Adding Steps

The FormBuilder provides two primary methods for adding steps:

add() - Unconditional Steps

The add() method at src/FormBuilder.php30-35 adds a step that always executes:

Parameters:

• $step: Closure that receives (array $responses, mixed $previousResponse) and returns the step result
• $name: Optional identifier for the step in the response array
• $ignoreWhenReverting: If true, skip this step when navigating backward

The closure receives two arguments:

1. $responses: Array of all responses collected so far
2. $previousResponse: The previous response for this specific step (when returning to it)

Sources: src/FormBuilder.php30-35

addIf() - Conditional Steps

The addIf() method at src/FormBuilder.php40-45 adds a step that executes only when a condition is met:

The $condition parameter can be:

• A boolean value for static conditions
• A Closure(array $responses): bool for dynamic conditions based on previous responses

Example:

Sources: src/FormBuilder.php40-45 src/FormStep.php38-46

---

Prompt Methods

The FormBuilder provides convenience methods for all standard prompts. These methods wrap the corresponding helper functions and automatically integrate them into the form flow.

Input Prompts

Method	Purpose	File Reference
text()	Single-line text input	src/FormBuilder.php93-96
textarea()	Multi-line text input	src/FormBuilder.php101-104
password()	Masked text input	src/FormBuilder.php109-112
select()	Single selection from list	src/FormBuilder.php120-123
multiselect()	Multiple selections from list	src/FormBuilder.php131-134
confirm()	Yes/No confirmation	src/FormBuilder.php139-142
pause()	Wait for user to continue	src/FormBuilder.php147-150
suggest()	Text input with autocomplete	src/FormBuilder.php157-160
search()	Dynamic search with callback	src/FormBuilder.php168-171
multisearch()	Multiple selection with search	src/FormBuilder.php178-181

All methods accept a $name parameter for step identification and return $this for method chaining.

Sources: src/FormBuilder.php93-181

Display Methods

Display components can also be added to forms. These are automatically marked with ignoreWhenReverting: true since they don't collect input:

Method	Purpose	File Reference
note()	Display a note	src/FormBuilder.php196-199
error()	Display an error message	src/FormBuilder.php204-207
warning()	Display a warning	src/FormBuilder.php212-215
alert()	Display an alert	src/FormBuilder.php220-223
info()	Display informational message	src/FormBuilder.php228-231
intro()	Display form introduction	src/FormBuilder.php236-239
outro()	Display form completion message	src/FormBuilder.php244-247
table()	Display tabular data	src/FormBuilder.php255-258
progress()	Display progress bar	src/FormBuilder.php269-272
spin()	Display spinner during operation	src/FormBuilder.php188-191

Sources: src/FormBuilder.php188-272

---

Internal Step Processing

The runPrompt() method at src/FormBuilder.php279-290 is the internal mechanism that wraps prompt functions into form steps:

The wrapper closure:

1. Removes the name parameter from arguments (used for step identification, not passed to prompt)
2. If previousResponse is not null and the prompt has a default parameter, replaces the default with the previous response
3. Calls the original prompt function with the modified arguments

This enables forms to remember and pre-fill previous answers when users navigate backward.

Sources: src/FormBuilder.php279-290

---

Execution Flow

The submit() method at src/FormBuilder.php52-88 executes the form using a sequential index-based loop with backward navigation support:

Reversion Handling

The execution flow handles backward navigation through the FormRevertedException:

1. For first step (index 0): Prompt::preventReverting() is called - pressing Ctrl+C exits the form
2. For subsequent steps: Prompt::revertUsing() is called with a closure that sets wasReverted = true
3. When reverted: The exception is caught, wasReverted flag is set, and index decrements
4. Skip logic: Steps marked with ignoreWhenReverting are skipped during backward navigation

Sources: src/FormBuilder.php52-88

---

Step Execution Details

The FormStep class at src/FormStep.php encapsulates individual step logic:

Key Methods

Constructor src/FormStep.php13-22:

• Normalizes boolean conditions into closures
• Stores all configuration

run() src/FormStep.php29-36:

• Checks if step should run using shouldRun()
• Returns null if condition is false
• Executes the step closure with $responses and $previousResponse
• Returns the step result

shouldRun() src/FormStep.php43-46:

• Evaluates the condition closure
• Returns boolean indicating if step should execute

shouldIgnoreWhenReverting() src/FormStep.php53-60:

• Returns true if step condition is false (step wouldn't run anyway)
• Returns the ignoreWhenReverting flag value if step would run
• Used to skip display-only steps during backward navigation

Sources: src/FormStep.php

---

Response Management

The FormBuilder maintains responses in an associative array at src/FormBuilder.php25:

Response Keys

Responses are keyed by:

1. Step name if provided via the name parameter
2. Numeric index if no name is provided

Response Access

Steps can access previous responses through the $responses parameter passed to their closures:

Response Persistence

When navigating backward to a step:

1. The previousResponse parameter contains the previous answer
2. For prompt methods, this is automatically used as the new default value
3. Custom closures can access it via the second parameter

Sources: src/FormBuilder.php25 src/FormBuilder.php52-88 src/FormBuilder.php279-290

---

Backward Navigation System

Backward navigation is implemented through the FormRevertedException and the Prompt class's revert handling:

Revert Modes

First Step src/FormBuilder.php71:

• Ctrl+C exits the form entirely
• No previous step to return to

Subsequent Steps src/FormBuilder.php69-70:

• Ctrl+C triggers the revert callback
• Sets flag to navigate backward

After Form Completion src/FormBuilder.php85:

• Resets revert behavior for subsequent prompts

Sources: src/FormBuilder.php52-88 src/Exceptions/FormRevertedException.php

---

Skipping Steps During Reversion

Steps can be configured to be skipped when navigating backward using the ignoreWhenReverting parameter:

Automatic Skip for Display Components

Display methods automatically set ignoreWhenReverting: true at src/FormBuilder.php279-290:

Display functions like note(), error(), intro(), etc., pass true for this parameter since they don't collect user input.

Skip Logic

The logic at src/FormBuilder.php60-64:

This ensures:

1. When moving backward (wasReverted === true)
2. And not at the first step ($index > 0)
3. Steps marked to ignore are skipped
4. Index decrements again to continue backward

Example:

When the user presses Ctrl+C at the email prompt, the note is skipped and they return directly to the name prompt.

Sources: src/FormBuilder.php60-64 src/FormBuilder.php279-290 src/FormStep.php53-60

---

Conditional Step Evaluation

Conditional steps created with addIf() are evaluated each time they're encountered:

Dynamic Conditions

Conditions are re-evaluated on each pass, including when returning to a step via backward navigation:

If the user:

1. Selects "business" → company name prompt appears
2. Presses Ctrl+C → returns to account type
3. Changes to "personal" → company name prompt is skipped
4. Continues forward → next step after conditional

The condition is evaluated each time based on current response values.

Sources: src/FormStep.php29-46 src/FormBuilder.php40-45

---

Complete Example

This form demonstrates:

• Named steps for organized responses
• Input validation
• Conditional steps based on previous answers
• Multiple prompt types
• Display components (intro/outro) that are skipped during reversion
• Backward navigation support (Ctrl+C at any step except the first)

Sources: src/FormBuilder.php src/FormStep.php