State Management and Validation

This document explains how prompts manage their internal state, the lifecycle of state transitions, and the validation mechanisms that ensure user input meets requirements. It covers the five primary states (initial, active, error, submit, cancel), validation callbacks, error handling, and value transformation.

For information about the complete prompt lifecycle and execution flow, see The Prompt Lifecycle. For terminal-specific concerns like raw mode and cursor control, see Terminal Integration.

---

Prompt State Overview

Every prompt instance maintains a $state property that tracks its current lifecycle phase. The state determines how the prompt renders and whether it continues accepting input.

State Machine Diagram

Sources: src/Prompt.php29 src/Prompt.php291-298 src/Prompt.php315-322 src/Prompt.php327-366

---

State Properties

The Prompt base class declares several properties that manage state and validation:

Property	Type	Purpose	Default Value
$state	string	Current lifecycle state	'initial'
$error	string	Validation error message to display	''
$required	bool|string	Whether input is required; custom error message if string	N/A
$validate	mixed	Validation callback or rules	N/A
$validated	bool	Whether validation has been triggered at least once	false
$transform	?Closure	Value transformation callback applied before validation	null
$cancelMessage	string	Message displayed when prompt is cancelled	'Cancelled.'

Sources: src/Prompt.php27-74

---

State Transitions

Initial → Active

The initial state is set at instantiation. On the first call to render(), the prompt transitions to active:

Sources: src/Prompt.php291-298

Active → Submit

When the user completes input (typically by pressing Enter), the prompt calls submit(), which validates the value. If validation passes, state becomes submit:

The submit state signals the main loop to return the value and exit.

Sources: src/Prompt.php315-322

Active → Error

Validation failures transition the prompt to error state. The $error property is populated with the failure message:

Sources: src/Prompt.php395-419

Error → Active

On the next key press, the prompt automatically resets from error to active, allowing the user to correct their input:

Sources: src/Prompt.php329-331

Active → Cancel

Two key combinations trigger cancellation:

1. Ctrl+C: Unconditional cancellation that exits or invokes a custom cancel handler
2. Ctrl+U: Reversion (used in forms) if revertUsing callback is registered

Sources: src/Prompt.php339-359

---

Validation System

Validation Flow Diagram

Sources: src/Prompt.php315-322 src/Prompt.php371-420

Required Validation

The $required property enables mandatory input validation. It accepts:

• false: No requirement (default for many prompts)
• true: Required with default "Required." error message
• string: Required with custom error message

The isInvalidWhenRequired() method checks if the value is empty:

Sources: src/Prompt.php395-400 src/Prompt.php425-428

Custom Validation

Prompts support two validation approaches:

1. Instance-Level Validation

Set the $validate property to a closure that receives the transformed value:

The callback should return:

• null if validation passes
• string error message if validation fails

Sources: src/Prompt.php406-410

2. Global Validation

Register a global validator using Prompt::validateUsing():

This callback receives the entire prompt instance, enabling validation logic that depends on prompt state or configuration.

Sources: src/Prompt.php253-256 src/Prompt.php408

Validation Timing

The $validated flag tracks whether validation has been triggered. Once true, validation runs continuously on every key press:

This provides real-time feedback after the user's first submission attempt.

Sources: src/Prompt.php361-363

---

Error State Handling

Error Display

When in error state, the theme renderer displays the $error message. The exact presentation depends on the renderer implementation (see Prompt-Specific Renderers), but typically uses red/error styling.

Error Recovery

The automatic error → active transition on the next key press allows users to immediately correct their input without manual state resets. The error message persists until the next render cycle.

Sources: src/Prompt.php329-331

Validation Error Types

Scenario	Error Message	Set In
Required field empty	$required (if string) or "Required."	Prompt.php395-399
Custom validation fails	Return value from $validate callback	Prompt.php407-418
Global validation fails	Return value from validateUsing callback	Prompt.php408-418
Reversion not allowed	"This cannot be reverted."	Prompt.php342

---

Value Transformation

Before validation, the prompt applies an optional transformation via the $transform callback:

Transformations allow prompts to:

• Normalize input (e.g., trim whitespace, lowercase)
• Convert types (e.g., string to integer)
• Map values (e.g., option labels to option values)

The transformed value is what gets validated and returned to the caller.

Sources: src/Prompt.php371-386

---

State in Non-Interactive Components

Some components like Progress use a simplified state model:

State	Meaning in Progress
active	Progress bar is running
submit	Progress completed successfully
cancel	Progress interrupted (Ctrl+C)
error	Exception occurred during iteration

The Progress class sets these states directly during its lifecycle:

Progress bars do not use the standard prompt() method and therefore skip validation entirely.

Sources: src/Progress.php100-141 src/Progress.php78

---

State-Based Rendering Integration

Renderers use the prompt's state to determine output:

This pattern allows themes to customize presentation per state while keeping state logic centralized in the Prompt base class. See The Base Renderer and Prompt-Specific Renderers for rendering details.

Sources: Referenced in diagram context; actual implementation in renderer classes