Text Input Prompts

This page documents the three text input prompt types in the hypervel/prompts library: single-line text input (text()), multi-line textarea input (textarea()), and hidden password input (password()). These prompts capture free-form textual user input from the terminal.

For selection-based prompts where users choose from predefined options, see Selection Prompts. For prompts with dynamic search functionality, see Search and Suggest Prompts.

Overview

Text input prompts provide a simple interface for capturing string input from users. All three prompt types share a common parameter set and extend the base Prompt abstraction, but differ in their input behavior and visual presentation.

Sources: src/Prompt.php15-449 src/helpers.php10-38

Prompt Type Comparison

Prompt Type	Helper Function	Input Style	Key Feature	Use Case
TextPrompt	text()	Single line	Placeholder support	Names, emails, short strings
TextareaPrompt	textarea()	Multi-line	Configurable rows	Descriptions, comments, paragraphs
PasswordPrompt	password()	Hidden characters	No visual feedback	Passwords, secrets, tokens

Sources: src/helpers.php10-38

Common Parameters

All three text input prompt types accept the following parameters through their helper functions:

Parameter	Type	Default	Description
$label	string	Required	The prompt question or label displayed to the user
$placeholder	string	''	Gray text shown when input is empty (not available for password())
$default	string	''	Pre-filled value; user can edit or accept (not available for password())
$required	bool|string	false	Whether input is required; string value becomes custom error message
$validate	mixed	null	Validation callback or rules; receives input value, returns error string or null
$hint	string	''	Help text displayed below the prompt
$transform	?Closure	null	Transformation callback applied to final value before return
$rows	int	5	Number of visible rows (textarea only)

Sources: src/helpers.php14-37 src/Prompt.php54-64

Architecture: Parameter Flow

Sources: src/helpers.php14-37 src/Prompt.php56-64 src/Prompt.php104-161

TextPrompt: Single-Line Input

The text() function creates a TextPrompt instance for capturing single-line string input. This is the most common text input prompt type.

Function Signature

Behavior

• Input Handling: Captures characters until Enter is pressed
• Default Value: Pre-populates the input field; user can clear or modify
• Placeholder: Displays gray text when input is empty
• Return Type: Always returns a string

Example Usage Scenarios

Scenario	Parameters	Notes
Simple text	text('Enter your name')	No validation, optional input
Required text	text('Email', required: true)	Must provide non-empty value
With default	text('Username', default: 'admin')	User can accept or change
Custom validation	text('Email', validate: fn($v) => filter_var($v, FILTER_VALIDATE_EMAIL) ? null : 'Invalid email')	Returns error string on failure

Sources: src/helpers.php14-17

TextareaPrompt: Multi-Line Input

The textarea() function creates a TextareaPrompt instance for capturing multi-line text input, useful for longer content like descriptions or comments.

Function Signature

Unique Features

• $rows Parameter: Controls the number of visible lines in the text area (default: 5)
• Multi-line Editing: Users can navigate between lines with arrow keys
• Line Breaks: Preserves newline characters in the returned string

Behavior Differences from TextPrompt

Aspect	TextPrompt	TextareaPrompt
Input termination	Single Enter press	Ctrl+D or submission key
Line breaks	Not allowed	Preserved in output
Visible area	Single line	Multiple rows (configurable)
Navigation	Left/right arrows only	Arrow keys for 2D navigation

Sources: src/helpers.php24-27

PasswordPrompt: Hidden Input

The password() function creates a PasswordPrompt instance for capturing sensitive input without visual feedback.

Function Signature

Security Characteristics

• No Visual Feedback: Characters are not displayed or masked with asterisks
• No Default Value: Password prompts do not support pre-filled values for security reasons
• No Placeholder Display: The $placeholder parameter exists for API consistency but is not rendered
• Memory Handling: Returns value as string; caller responsible for secure handling

Validation Considerations

Password prompts commonly use validation for:

• Minimum length requirements
• Character complexity rules
• Confirmation matching (use two separate password prompts)

Example with Validation

Sources: src/helpers.php34-37

Validation System

All text input prompts support validation through the $validate parameter, which integrates with the base Prompt validation mechanism.

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

Validation Rules

Rule Type	Implementation	Return Value	Example
Required	$required = true	Built-in check	Empty string rejected
Custom message	$required = "Custom error"	Uses custom string	"Email is required"
Callable	$validate = fn($v) => ...	Error string or null	Length, format checks
Multi-rule	Chain multiple checks	First error returned	Combine length + format

Validation Callback Pattern

The $validate callable receives the transformed value and must return:

• null if validation passes
• Non-empty string error message if validation fails

Sources: src/Prompt.php406-419

Transformation System

The $transform parameter allows modification of the user's input before it is returned. Transformations are applied after validation.

Transformation Flow

Sources: src/Prompt.php383-386 src/Prompt.php371-378

Common Transformation Patterns

Pattern	Purpose	Example
Normalization	Standardize format	fn($v) => strtolower(trim($v))
Type casting	Convert to specific type	fn($v) => (int) $v
Sanitization	Remove unwanted characters	fn($v) => preg_replace('/[^a-z]/i', '', $v)
Formatting	Apply consistent structure	fn($v) => ucwords($v)

Example: Combined Validation and Transformation

Sources: src/Prompt.php56-64 src/Prompt.php371-378 src/Prompt.php383-386

Integration with Prompt Lifecycle

Text input prompts follow the standard prompt lifecycle defined in the base Prompt class. Key lifecycle states relevant to text input:

State	Description	Trigger
initial	First render before user interaction	Constructor completion
active	Accepting user input	After first render
error	Validation failed	Validation callback returned error string
submit	Valid input, ready to return	Validation passed
cancel	User cancelled prompt	Ctrl+C pressed

For detailed information about the prompt lifecycle and state transitions, see The Prompt Lifecycle and State Management and Validation.

Sources: src/Prompt.php29 src/Prompt.php104-161 src/Prompt.php315-322

Required Field Behavior

The $required parameter controls whether empty input is acceptable. It can be either a boolean or a custom error message string.

Required Parameter Modes

Sources: src/Prompt.php54 src/Prompt.php395-400

Empty Value Definition

The base Prompt class defines empty values as:

• Empty string: ''
• Empty array: []
• Boolean false: false
• Null: null

For text input prompts, only empty string '' is typically relevant.

Sources: src/Prompt.php425-428

Example Required Field Usage

Sources: src/helpers.php14-37 src/Prompt.php395-400