Getting Started

This page guides you through installing the hypervel/prompts library, understanding its dependencies, and using it to create your first interactive CLI prompt. It covers installation via Composer, the library's structural organization, and basic usage patterns through helper functions. For detailed documentation of all available prompt types, see Prompt Types. For information about creating multi-step forms, see Multi-Step Forms.

Installation

The hypervel/prompts library is installed via Composer. It requires PHP 8.2 or higher and several dependencies that provide terminal rendering and CLI infrastructure.

Composer Installation Flow

To install the library, run:

This command adds the package to your project's composer.json and installs it to the vendor/ directory. The library's PSR-4 autoloader and helper functions are automatically registered via Composer's autoload mechanism.

Sources: composer.json1-39

Dependencies

The library requires several external packages and PHP extensions to function. These are automatically installed by Composer as transitive dependencies.

Dependency	Version	Purpose
php	^8.2	Minimum PHP runtime version
ext-mbstring	*	Multi-byte string handling for internationalization
composer-runtime-api	^2.2	Access to Composer runtime information
symfony/console	^6.2|^7.0	CLI framework infrastructure
nunomaduro/termwind	^2.0	HTML-like terminal styling

Dependency Roles

PHP 8.2+: The library uses modern PHP features including typed properties, constructor property promotion, and match expressions. Version 8.2 is the minimum supported version.

ext-mbstring: Provides multi-byte safe string functions (mb_strlen, mb_substr, etc.) necessary for proper handling of Unicode text in prompts. This is critical for international character support and proper text truncation.

composer-runtime-api: Enables detection of the Composer runtime environment, used by the library to adapt behavior in different contexts.

symfony/console: Provides foundational CLI infrastructure including input/output streams, terminal detection, and ANSI support. The library uses Symfony Console's terminal manipulation capabilities.

nunomaduro/termwind: A styling engine that renders HTML-like markup to ANSI escape sequences. Used by the theme system to generate styled terminal output. See HTML-like Rendering with Termwind for details.

Sources: composer.json21-26

Library Structure

The hypervel/prompts package follows PSR-4 autoloading conventions and provides two entry points for developers.

Package Organization

The package structure consists of:

• src/helpers.php: Global helper functions that serve as the primary API. Automatically loaded by Composer via the files autoload section.
• src/*.php: Prompt class implementations following PSR-4 standard (Hypervel\Prompts namespace)
• src/Concerns/: Reusable traits providing cross-cutting functionality (scrolling, colors, cursor control, etc.)
• src/Themes/: Renderer classes that define visual presentation for each prompt type

PSR-4 Autoloading Configuration

The library registers two autoload mechanisms in composer.json:

The PSR-4 mapping means that the class Hypervel\Prompts\TextPrompt is located at src/TextPrompt.php. The files directive ensures that all helper functions are available globally without requiring explicit imports.

Sources: composer.json13-19

Basic Usage

The library provides two ways to create prompts: global helper functions (recommended) and direct class instantiation. Helper functions are the simplest approach and suitable for most use cases.

Helper Function Pattern

Each helper function follows this pattern:

1. Accept parameters for the specific prompt type
2. Capture all parameters via get_defined_vars()
3. Instantiate the corresponding prompt class using the spread operator
4. Call prompt() to execute the interaction
5. Return the result (type varies by prompt)

Simple Text Input Example

The text() helper function is the most basic prompt type:

The function signature and implementation can be found at src/helpers.php9-16 It instantiates TextPrompt and immediately calls prompt().

Selection Example

The select() helper presents a list of options:

The function is defined at src/helpers.php24-36 and uses SelectPrompt internally.

Confirmation Example

The confirm() helper presents a yes/no choice:

The function is defined at src/helpers.php137-145 and returns a boolean value, unlike most other prompts that return strings.

Available Helper Functions

The library provides 18+ global helper functions. Here are the primary ones:

Function	Purpose	Return Type	Reference
text()	Single-line text input	string	#4.1
textarea()	Multi-line text input	string	#4.1
password()	Hidden text input	string	#4.1
select()	Single choice from list	string|int	#4.2
multiselect()	Multiple choices from list	array	#4.2
confirm()	Yes/No question	bool	#4.2
search()	Single choice with search	string|int	#4.3
multisearch()	Multiple choices with search	array	#4.3
suggest()	Text input with autocomplete	string	#4.3
pause()	Wait for user to press Enter	bool	#4.2
form()	Multi-step form builder	FormBuilder	#5
table()	Display tabular data	void	#4.4
progress()	Progress bar	Progress|array	#4.4
spinner()	Loading indicator	Spinner|mixed	#4.4
note()	Display styled message	void	#4.4
clear()	Clear terminal screen	void	#6.2

All helper functions are defined in src/helpers.php1-186 For comprehensive documentation of each prompt type, see Prompt Types.

Sources: src/helpers.php1-186

Direct Class Instantiation

While helper functions are recommended, you can also instantiate prompt classes directly. This approach provides more control and is useful in object-oriented contexts.

Class-Based Usage Pattern

Example:

All prompt classes extend the base Prompt class, which is documented in The Prompt System. The classes are located in the src/ directory with naming convention {Type}Prompt.php (e.g., TextPrompt.php, SelectPrompt.php).

Sources: src/helpers.php9-16 (shows how helpers instantiate classes)

Next Steps

After installing and understanding basic usage, explore these topics:

• Helper Functions - The Public API: Detailed documentation of all helper functions and their parameters
• Library Structure and Dependencies: In-depth explanation of package organization and dependency roles
• Prompt Types: Comprehensive guide to all 15+ prompt types organized by interaction pattern
• Multi-Step Forms: Learn to create sequential forms with the FormBuilder class
• Interactive Features: Understand event handling, validation, and scrolling mechanisms
• Styling and Formatting: Customize visual appearance with colors and themes

Sources: composer.json1-39 README.md1-4