Confirmation Prompts

This document covers the confirmation prompt types in the hypervel/prompts library: confirm() and pause(). These prompts are designed for binary choices (yes/no decisions) and flow control (pausing execution until user continues). Both return boolean values and provide simple, focused interactions.

For text-based input prompts, see Text Input Prompts. For multi-option selection, see Selection Prompts. For multi-step form flows, see Multi-Step Forms with FormBuilder.

---

Overview

The confirmation prompt system provides two primary functions:

Function	Purpose	Return Type	Interaction Style
confirm()	Ask user to confirm/deny an action	bool	Yes/No toggle with keyboard navigation
pause()	Pause execution until user presses Enter	bool	Simple press-to-continue

Both prompts are implemented as helper functions that instantiate their respective prompt classes and immediately call the prompt() method to begin interaction.

Sources: src/helpers.php67-85

---

Function Architecture

Sources: src/helpers.php67-85 src/ConfirmPrompt.php9-55

---

The confirm() Helper Function

The confirm() function prompts the user to make a binary yes/no decision. It provides extensive customization options while maintaining a simple default behavior.

Function Signature

function confirm(
 string $label,
 bool $default = true,
 string $yes = 'Yes',
 string $no = 'No',
 bool|string $required = false,
 mixed $validate = null,
 string $hint = '',
 ?Closure $transform = null
): bool

Parameters

Parameter	Type	Default	Description
$label	string	required	The question or prompt text displayed to the user
$default	bool	true	The default selection (true = Yes, false = No)
$yes	string	'Yes'	Label for the affirmative option
$no	string	'No'	Label for the negative option
$required	bool|string	false	Whether a response is required, or custom error message
$validate	mixed	null	Validation callback or rules
$hint	string	''	Hint text displayed below the prompt
$transform	?Closure	null	Optional transformation applied to the value before returning

Implementation Details

The helper function uses variadic parameter expansion to forward all arguments to the ConfirmPrompt constructor:

src/helpers.php71-74

This pattern is consistent across all helper functions in the library, providing a clean API while delegating implementation to class-based components.

Sources: src/helpers.php67-75 src/ConfirmPrompt.php19-38

---

The pause() Helper Function

The pause() function is a simplified variant that simply waits for the user to press Enter to continue. It's useful for creating breakpoints in CLI flows where you want to ensure the user has read previous output before proceeding.

Function Signature

function pause(string $message = 'Press enter to continue...'): bool

Parameters

Parameter	Type	Default	Description
$message	string	'Press enter to continue...'	Message displayed to the user

Unlike confirm(), the pause() function has no customization options for validation, transformation, or alternative labels. It returns true when the user presses Enter, providing a simple continue/cancel flow control mechanism.

Sources: src/helpers.php77-85

---

ConfirmPrompt Class Architecture

The ConfirmPrompt class extends the base Prompt class and implements binary choice interaction through keyboard event handling.

Class Properties

State Management

The ConfirmPrompt maintains its state through the confirmed property:

• Initialization: Set to the value of $default parameter src/ConfirmPrompt.php29
• Updates: Modified via keyboard event handlers
• Retrieval: Accessed through the value() method src/ConfirmPrompt.php43-46

The label() method returns the string representation of the current selection ($yes or $no) based on the confirmed state src/ConfirmPrompt.php49-54

Sources: src/ConfirmPrompt.php9-55

---

Keyboard Event Handling

The ConfirmPrompt constructor registers a comprehensive set of keyboard handlers to allow multiple interaction patterns:

Key Mapping Implementation

The event handler is registered in the constructor using a match expression src/ConfirmPrompt.php31-37:

• 'y': Sets confirmed to true
• 'n': Sets confirmed to false
• Navigation keys: Toggle the confirmed state
  • TAB, arrow keys (UP/DOWN/LEFT/RIGHT)
  • Ctrl navigation (CTRL_P/CTRL_F/CTRL_N/CTRL_B)
  • Vim-style keys (h, j, k, l)
• ENTER: Submits the prompt

This design supports multiple interaction styles: direct selection (y/n), keyboard navigation, and vim-style navigation, making the prompt accessible to users with different preferences.

Sources: src/ConfirmPrompt.php31-37

---

Prompt Value Flow

Value Transformation

If a transform closure is provided, it is applied to the boolean value before returning. This allows for custom post-processing, though it's less commonly needed for boolean values than for text inputs.

Sources: src/ConfirmPrompt.php9-55 src/helpers.php67-75

---

Validation and Requirements

The confirm() function supports validation through two mechanisms:

Required Parameter

The $required parameter can be:

• false (default): No validation, any response accepted
• true: Generic required message
• string: Custom error message if validation fails

Custom Validation

The $validate parameter accepts a validation callback or rule set that will be applied to the boolean value before the prompt completes. This allows for context-specific validation logic.

Property Definitions

All validation-related properties are defined in the constructor src/ConfirmPrompt.php19-28:

• $required src/ConfirmPrompt.php24
• $validate src/ConfirmPrompt.php25

Sources: src/ConfirmPrompt.php19-28 src/helpers.php71

---

Return Value and Label Access

The ConfirmPrompt class provides two methods for accessing the user's choice:

value() Method

Returns the raw boolean value src/ConfirmPrompt.php43-46:

public function value(): bool
{
 return $this->confirmed;
}

This is used internally by the prompt system to determine the final return value.

label() Method

Returns the string representation of the selection src/ConfirmPrompt.php49-54:

public function label(): string
{
 return $this->confirmed ? $this->yes : $this->no;
}

This is used by the rendering system to display which option is currently selected or was ultimately chosen.

Sources: src/ConfirmPrompt.php43-54

---

Integration with Prompt System

The confirmation prompts integrate with the broader prompt system through:

1. Base Class Inheritance: Both extend Prompt base class
2. Event System: Use the Events trait for keyboard handling (see Event System and Interactivity)
3. Theme System: Support pluggable renderers via Themes trait (see Theming and Rendering System)
4. Validation: Share validation infrastructure with other prompt types

Sources: src/ConfirmPrompt.php9 src/helpers.php67-85

---

Use in Multi-Step Forms

Confirmation prompts are commonly used within FormBuilder workflows (see Multi-Step Forms with FormBuilder) to confirm user decisions before proceeding or to gate access to subsequent steps.

The boolean return value integrates seamlessly with conditional form logic, allowing forms to branch based on user confirmation.

Sources: src/helpers.php67-75