Quick Start - Your First Prompt

Purpose and Scope

This guide demonstrates how to create your first interactive CLI prompt using hypervel/prompts. It covers the basic workflow of using helper functions to collect user input, showing the simplest patterns to get started quickly. For detailed information about specific prompt types, see Interactive Prompts. For multi-step forms and complex workflows, see Multi-Step Forms with FormBuilder.

---

Your First Prompt: Text Input

The simplest way to use hypervel/prompts is through global helper functions. Here's a complete example that prompts for a user's name:

When executed, this creates an interactive prompt that:

1. Displays the label "What is your name?"
2. Shows a placeholder value "John Doe"
3. Waits for user input
4. Validates that input is not empty (due to required: true)
5. Returns the entered string

Sources: src/helpers.php10-18

---

Helper Function to Class Mapping

All helper functions instantiate concrete Prompt subclasses and call their prompt() method. This diagram shows the direct mapping:

Implementation Pattern: Each helper function follows the same pattern shown in src/helpers.php14-17:

This creates a prompt instance with all function parameters and immediately calls its prompt() method to start the interaction.

Sources: src/helpers.php10-133

---

Basic Execution Flow

Understanding what happens when you call a helper function:

Key Methods:

• prompt() - Entry point that manages the entire lifecycle src/Prompt.php104-161
• render() - Updates terminal display src/Prompt.php281-310
• handleKeyPress() - Processes keyboard input src/Prompt.php327-366
• submit() - Validates and finalizes input src/Prompt.php315-322

Sources: src/Prompt.php104-161 src/Prompt.php281-310 src/Prompt.php327-366

---

Common Prompt Examples

Single Line Text Input

Sources: src/helpers.php10-18

Selection from Options

Sources: src/helpers.php40-51

Multiple Selections

Sources: src/helpers.php53-65

Yes/No Confirmation

Sources: src/helpers.php67-75

Password Input

Sources: src/helpers.php30-38

---

Parameter Reference

Common parameters available across helper functions:

Parameter	Type	Purpose	Available In
label	string	Question/prompt text	All prompts
placeholder	string	Placeholder value shown	text, textarea, search, suggest
default	mixed	Default value	All prompts
required	bool|string	Validation - if string, used as error message	All prompts
validate	callable|null	Custom validation closure	All prompts
hint	string	Help text displayed below prompt	All prompts
transform	Closure|null	Transform value before returning	All prompts
options	array	Available choices	select, multiselect, suggest
scroll	int	Number of visible options	select, multiselect, search

Sources: src/helpers.php10-133

---

Return Values and Types

Each helper function returns a specific type based on the prompt:

Key Points:

• Text-based prompts (text, textarea, password, suggest) always return string
• Single selection prompts (select, search) return the selected option's key (not the display value)
• Multi-selection prompts (multiselect, multisearch) return an array of keys
• Boolean prompts (confirm, pause) return bool

Example with option keys:

Sources: src/helpers.php10-133

---

Validation and Error Handling

All prompts support two validation mechanisms:

Required Field Validation

Implementation in src/Prompt.php395-400:

• Checks if value is empty string, empty array, false, or null
• Displays default "Required." or custom message
• Prevents submission until valid input provided

Custom Validation

Validation Rules src/Prompt.php406-420:

• Validator must return string (error message) or null (valid)
• Validation runs on Enter key press
• Prompt state changes to 'error' if validation fails
• Error message displayed until user corrects input

Sources: src/Prompt.php391-420

---

Value Transformation

Transform the final value before it's returned:

Transformation occurs src/Prompt.php371-378:

1. After user submits (presses Enter)
2. Before validation runs
3. Before value is returned to caller

Sources: src/Prompt.php371-386

---

Terminal State Management

The library automatically manages terminal state during prompt execution:

Action	When	Purpose
setTty('-icanon -isig -echo')	Before rendering	Enable raw mode for character-by-character input
hideCursor()	Before rendering	Hide blinking cursor during interactive display
restoreCursor()	After submission/cancellation	Show cursor again
restoreTty()	After submission/cancellation	Restore normal terminal mode

Handled automatically by Prompt::prompt() method src/Prompt.php104-161 and destructor src/Prompt.php443-448

Sources: src/Prompt.php104-161 src/Prompt.php443-448

---

Keyboard Controls

Standard keyboard shortcuts available in all interactive prompts:

Key	Action	Implementation
Enter	Submit current value	Calls submit() method
Ctrl+C	Cancel prompt and exit	Triggers terminal exit or custom cancel handler
Ctrl+U	Revert to previous form step	Used in multi-step forms (see FormBuilder)

Additional keys specific to prompt types (selection/search prompts):

Key	Action
↑/↓	Navigate options
Space	Toggle selection (multiselect)
Letters	Type to search/filter

Sources: src/Prompt.php133-154 src/Prompt.php327-366

---

Next Steps

Now that you understand the basics:

• Explore all prompt types: See Interactive Prompts for detailed documentation of each prompt type
• Build multi-step forms: Learn about FormBuilder for complex workflows with backward navigation
• Customize display: See Theming and Rendering System for visual customization
• Add progress indicators: See Progress Bars and Spinners for long-running operations
• Display data: Use Tables and Notes for output formatting

Sources: src/helpers.php1-262 src/Prompt.php1-450