Helper Functions - The Public API

Purpose and Scope

This page documents the complete public API of the hypervel/prompts library—the global helper functions defined in src/helpers.php that serve as the primary developer interface. These functions provide a clean, declarative syntax for creating interactive CLI prompts and display components.

For detailed information about the underlying prompt classes and lifecycle management, see Core Architecture. For multi-step form orchestration, see Multi-Step Forms with FormBuilder. For display component internals, see Display Components.

---

Overview

The library exposes 23 global helper functions in the Hypervel\Prompts namespace. Each function instantiates a specific prompt or display class and immediately invokes its execution method (prompt() or display()), returning the result directly to the caller.

Sources: src/helpers.php1-262

---

Function-to-Class Mapping

The helper functions serve as thin wrappers around underlying prompt classes, following a consistent pattern:

Sources: src/helpers.php1-262

---

Function Categories

The 23 helper functions are organized into 7 functional categories:

Category	Functions	Purpose
Text Input	text(), textarea(), password()	Single/multi-line text collection
Selection	select(), multiselect()	Choose from predefined options
Search & Suggest	suggest(), search(), multisearch()	Dynamic option filtering and autocomplete
Confirmation	confirm(), pause()	Yes/no decisions and flow control
Messages	note(), error(), warning(), alert(), info(), intro(), outro()	Non-interactive status messages
Visualization	table(), progress(), spin()	Data display and loading indicators
Utilities	clear(), form()	Terminal control and form orchestration

Sources: src/helpers.php1-262

---

Text Input Functions

text()

Prompts the user for single-line text input.

Parameter	Type	Default	Description
$label	string	required	The prompt question or instruction
$placeholder	string	''	Grayed placeholder text shown when empty
$default	string	''	Pre-filled default value
$required	bool|string	false	If true or string, input cannot be empty; string used as error message
$validate	mixed	null	Validation callable or rule (see State Management and Validation)
$hint	string	''	Helper text displayed below the prompt
$transform	?Closure	null	Transform the final value before returning

Returns: string - The user's input after validation and transformation

Implementation: Instantiates TextPrompt with spread arguments and calls prompt().

Sources: src/helpers.php10-18

---

textarea()

Prompts the user for multi-line text input.

Parameter	Type	Default	Description
$label	string	required	The prompt question or instruction
$placeholder	string	''	Placeholder text for empty input
$default	string	''	Pre-filled default value
$required	bool|string	false	Validation for non-empty input
$validate	mixed	null	Custom validation logic
$hint	string	''	Helper text
$rows	int	5	Number of visible rows in the textarea
$transform	?Closure	null	Value transformer

Returns: string - The user's multi-line input

Implementation: Instantiates TextareaPrompt and calls prompt().

Sources: src/helpers.php20-28

---

password()

Prompts the user for password input with hidden characters.

Parameter	Type	Default	Description
$label	string	required	The prompt question
$placeholder	string	''	Placeholder text
$required	bool|string	false	Non-empty requirement
$validate	mixed	null	Validation logic
$hint	string	''	Helper text
$transform	?Closure	null	Value transformer

Note: No $default parameter—passwords are not pre-filled for security.

Returns: string - The password (actual input, not masked)

Implementation: Instantiates PasswordPrompt and calls prompt().

Sources: src/helpers.php30-38

---

Selection Functions

select()

Prompts the user to select a single option from a list using arrow keys.

Parameter	Type	Default	Description
$label	string	required	The prompt question
$options	array|Collection	required	Associative array of keys to labels
$default	int|string|null	null	Key of the default selected option
$scroll	int	5	Number of visible options before scrolling
$validate	mixed	null	Validation logic
$hint	string	''	Helper text
$required	bool|string	true	Requires selection (default behavior)
$transform	?Closure	null	Transform the selected key

Returns: int|string - The key of the selected option

Implementation: Instantiates SelectPrompt which uses the Scrolling trait for list navigation.

Sources: src/helpers.php40-51

---

multiselect()

Prompts the user to select multiple options using the spacebar.

Parameter	Type	Default	Description
$label	string	required	The prompt question
$options	array|Collection	required	Associative array of keys to labels
$default	array|Collection	[]	Array of keys that are pre-selected
$scroll	int	5	Visible options before scrolling
$required	bool|string	false	Requires at least one selection
$validate	mixed	null	Validation logic
$hint	string	'Use the space bar...'	Helper text (note default)
$transform	?Closure	null	Transform the array of selected keys

Returns: array - Array of selected option keys

Implementation: Instantiates MultiSelectPrompt which uses the Scrolling trait.

Sources: src/helpers.php53-65

---

Search and Suggest Functions

suggest()

Prompts the user for text input with autocomplete suggestions.

Parameter	Type	Default	Description
$label	string	required	The prompt question
$options	array|Closure|Collection	required	Array of suggestions or Closure(string): array
$placeholder	string	''	Placeholder text
$default	string	''	Default value
$scroll	int	5	Visible suggestions
$required	bool|string	false	Non-empty requirement
$validate	mixed	null	Validation logic
$hint	string	''	Helper text
$transform	?Closure	null	Value transformer

Returns: string - The user's final text input (may or may not match a suggestion)

Note: The $options parameter accepts a Closure(string): array<string> for dynamic suggestion generation based on current input.

Implementation: Instantiates SuggestPrompt and calls prompt().

Sources: src/helpers.php97-107

---

search()

Allows the user to search through dynamically filtered options and select one.

Parameter	Type	Default	Description
$label	string	required	The prompt question
$options	Closure	required	Closure(string): array<int|string, string> that returns filtered options
$placeholder	string	''	Search input placeholder
$scroll	int	5	Visible options
$validate	mixed	null	Validation logic
$hint	string	''	Helper text
$required	bool|string	true	Requires selection
$transform	?Closure	null	Transform the selected key

Returns: int|string - The key of the selected option

Note: The $options closure receives the current search query and must return an associative array of matching options.

Implementation: Instantiates SearchPrompt which uses the TypedValue and Scrolling traits.

Sources: src/helpers.php109-120

---

multisearch()

Allows the user to search and select multiple options using the spacebar.

Parameter	Type	Default	Description
$label	string	required	The prompt question
$options	Closure	required	Closure(string): array<int|string, string> for filtering
$placeholder	string	''	Search input placeholder
$scroll	int	5	Visible options
$required	bool|string	false	Requires at least one selection
$validate	mixed	null	Validation logic
$hint	string	'Use the space bar...'	Helper text
$transform	?Closure	null	Transform the array of selected keys

Returns: array - Array of selected option keys

Implementation: Instantiates MultiSearchPrompt and calls prompt().

Sources: src/helpers.php122-133

---

Confirmation and Control Flow Functions

confirm()

Prompts the user for a yes/no decision.

Parameter	Type	Default	Description
$label	string	required	The question to confirm
$default	bool	true	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	Validation requirement
$validate	mixed	null	Custom validation
$hint	string	''	Helper text
$transform	?Closure	null	Transform the boolean result

Returns: bool - true if user selected Yes, false if No

Implementation: Instantiates ConfirmPrompt and calls prompt().

Sources: src/helpers.php67-75

---

pause()

Displays a message and waits for the user to press Enter.

Parameter	Type	Default	Description
$message	string	'Press enter to continue...'	The message to display

Returns: bool - Always returns true (unless cancelled with Ctrl+C)

Implementation: Instantiates PausePrompt and calls prompt(). Typically used for flow control in scripts.

Sources: src/helpers.php77-85

---

Message Display Functions

All message functions instantiate the Note class with different type parameters, which controls styling in the theme renderers.

Sources: src/helpers.php150-218

---

note()

Displays a generic note with optional type.

Parameter	Type	Default	Description
$message	string	required	The message to display
$type	?string	null	Optional type for styling (e.g., 'error', 'info')

Returns: void

Sources: src/helpers.php150-158

---

error()

Displays an error message (red styling in default theme).

Implementation: Calls new Note($message, 'error')->display()

Sources: src/helpers.php160-168

---

warning()

Displays a warning message (yellow styling in default theme).

Implementation: Calls new Note($message, 'warning')->display()

Sources: src/helpers.php170-178

---

alert()

Displays an alert message (highlighted styling).

Implementation: Calls new Note($message, 'alert')->display()

Sources: src/helpers.php180-188

---

info()

Displays an informational message (blue styling in default theme).

Implementation: Calls new Note($message, 'info')->display()

Sources: src/helpers.php190-198

---

intro()

Displays an introduction message (typically used at script start).

Implementation: Calls new Note($message, 'intro')->display()

Sources: src/helpers.php200-208

---

outro()

Displays a closing message (typically used at script end).

Implementation: Calls new Note($message, 'outro')->display()

Sources: src/helpers.php210-218

---

Visualization Functions

table()

Displays tabular data with optional headers.

Parameter	Type	Default	Description
$headers	array|Collection	[]	Array of column header strings, or if $rows is null, the data rows
$rows	array|Collection|null	null	Array of row arrays; if null, $headers contains the data

Returns: void

Note: The parameter overloading allows table($rows) or table($headers, $rows) syntax.

Implementation: Instantiates Table and calls display(). See Tables for detailed usage.

Sources: src/helpers.php220-231

---

progress()

Displays a progress bar for iterating over steps.

Parameter	Type	Default	Description
$label	string	required	Label displayed above the progress bar
$steps	int|iterable	required	Number of steps (int) or iterable to process
$callback	?Closure	null	Optional callback to execute for each step
$hint	string	''	Helper text

Returns:

• Progress instance if $callback is null (for manual control)
• array of callback return values if $callback is provided

Usage Patterns:

1. Automatic iteration with callback:

2. Manual control:

Implementation: Instantiates Progress and optionally calls map($callback). See Progress Bars and Spinners for details.

Sources: src/helpers.php233-254

---

spin()

Displays a loading spinner while executing a callback.

Parameter	Type	Default	Description
$callback	Closure	required	The operation to execute
$message	string	''	Message displayed next to spinner

Returns: mixed - The return value of $callback

Implementation: Instantiates Spinner and calls spin($callback), which animates the spinner during callback execution.

Sources: src/helpers.php135-148

---

Utility Functions

clear()

Clears the terminal screen.

Returns: void

Implementation: Instantiates Clear and calls display(), which outputs ANSI escape sequences to clear the screen.

Sources: src/helpers.php87-95

---

form()

Creates a FormBuilder instance for multi-step forms.

Returns: FormBuilder - A new form builder instance

Usage: This is the entry point for creating multi-step forms with reversion support. See Multi-Step Forms with FormBuilder for comprehensive documentation.

Example:

Implementation: Simply instantiates and returns a new FormBuilder.

Sources: src/helpers.php256-261

---

Common Parameter Patterns

Several parameters appear consistently across multiple functions:

Validation Parameters

Parameter	Type	Description
$required	bool|string	If true, input cannot be empty; if string, used as custom error message
$validate	mixed	Custom validation: callable, regex pattern, or array of rules

See State Management and Validation for validation system details.

---

Transformation Parameter

Parameter	Type	Description
$transform	?Closure	Transform the final value before returning: Closure($value): mixed

The transformer receives the validated value and its return value becomes the function's return value.

---

Display Parameters

Parameter	Type	Description
$hint	string	Helper text displayed below the prompt
$placeholder	string	Placeholder text shown when input is empty

---

Scrolling Parameter

Parameter	Type	Default	Description
$scroll	int	5	Number of options visible before scrolling is activated

Used in select(), multiselect(), suggest(), search(), and multisearch().

---

Function Invocation Pattern

All helper functions follow a consistent implementation pattern:

Key Pattern Elements:

1. Argument spreading: Uses ...get_defined_vars() to pass all function parameters as constructor arguments
2. Immediate invocation: Calls prompt() for interactive prompts or display() for display components
3. Direct return: Returns the result directly to the caller
4. No state retention: Each call creates a fresh instance

This design ensures helper functions are stateless and side-effect-free (except for terminal I/O).

Sources: src/helpers.php1-262

---

Type System Integration

The helper functions leverage PHP's type system for developer ergonomics:

Collection Support

Functions accepting arrays also accept Hyperf\Collection\Collection instances:

• select(): $options parameter
• multiselect(): $options and $default parameters
• suggest(): $options parameter
• table(): $headers and $rows parameters
• progress(): $steps parameter (when iterable)

Union Types

Several functions use union types for flexibility:

Function	Parameter	Type	Purpose
select()	$default	int|string|null	Match key type in $options
select()	Return	int|string	Return the option key
multiselect()	$default	array|Collection	Accept multiple default keys
suggest()	$options	array|Closure|Collection	Static or dynamic suggestions
progress()	$steps	int|iterable	Count or items to process
progress()	Return	array|Progress	Based on $callback presence

Generic Type Annotations

The progress() function includes PHPDoc generics for type safety:

This enables IDEs to infer that calling progress('Label', $items, $callback) returns array<TReturn>, while progress('Label', 100) returns Progress<int>.

Sources: src/helpers.php237-243

---

Summary

The 23 helper functions provide a complete, declarative API for CLI interactions:

• 10 interactive prompts: text, textarea, password, select, multiselect, confirm, pause, suggest, search, multisearch
• 7 message displays: note, error, warning, alert, info, intro, outro
• 3 visualizations: table, progress, spin
• 3 utilities: clear, form, [plus FormBuilder method chaining]

All functions follow consistent parameter patterns (validation, transformation, hints) and are implemented as thin wrappers that instantiate prompt classes and invoke their lifecycle methods. The design prioritizes ease of use, type safety, and functional composition.

Sources: src/helpers.php1-262