Tables

Purpose and Scope

This document covers the Table display component in hypervel/prompts, which provides a simple way to display tabular data in the terminal with formatted headers and rows. Tables are non-interactive display components that render structured data and immediately return control to the application.

For interactive selection from lists, see Selection Prompts. For progress tracking during iterations, see Progress Bars and Spinners. For other display utilities like notes and messages, see Notes and Messages.

Sources: src/Table.php1-73 src/helpers.php220-231

---

Overview

The Table component extends the base Prompt class but operates as a display-only component. Unlike interactive prompts that capture user input, tables render tabular data and immediately transition to the submit state without waiting for user interaction.

Sources: src/Table.php9-73 src/helpers.php220-231

---

The table() Helper Function

The table() helper function provides the simplest API for displaying tables. It accepts headers and rows, creates a Table instance, and immediately displays it.

Function Signature

Location: src/helpers.php220-231

Parameters

Parameter	Type	Description
$headers	array|Collection	Table column headers, or rows if $rows is null
$rows	array|Collection|null	Table data rows, or null to use $headers as rows

Usage Patterns

The function supports two calling conventions:

Pattern 1: Headers + Rows

Pattern 2: Rows Only

When $rows is null, the $headers parameter is interpreted as row data and no header row is displayed.

Sources: src/helpers.php220-231 src/Table.php33-42

---

Data Structures

Headers Format

Headers can be specified as either simple strings or arrays of strings:

Format	Type	Example	Description
Simple	array<int, string>	['Name', 'Email']	Flat array of column headers
Complex	array<int, array<int, string>>	[['Name'], ['Email']]	Nested arrays for each column

Type Definition: src/Table.php14-16

Rows Format

Rows must be arrays of arrays, where each inner array represents a single row:

Type Definition: src/Table.php20-23

Example:

Collection Support

Both headers and rows accept Hyperf\Collection\Collection instances, which are automatically converted to arrays:

The constructor normalizes Collections using ->all(): src/Table.php40-41

Sources: src/Table.php14-42 src/helpers.php224-225

---

The Table Class

Class Structure

Location: src/Table.php9-73

Constructor

The Table constructor handles two calling patterns through parameter overloading:

Implementation Logic: src/Table.php33-42

This design allows both new Table($rows) and new Table($headers, $rows) patterns.

Public Methods

Method	Return Type	Description
display()	void	Alias for prompt(), renders the table
prompt()	bool	Renders table and returns true
value()	bool	Returns true (tables have no user input)

Sources: src/Table.php33-73

---

Rendering and Display Process

Execution Flow

Sources: src/Table.php47-64

The prompt() Method

Unlike interactive prompts that enter an input loop, Table::prompt() immediately renders and returns:

Location: src/Table.php55-64

Key Differences from Interactive Prompts:

1. No input loop - Does not call runPrompt() or process keyboard input
2. Immediate state transition - Sets state = 'submit' without validation
3. No user value - Returns true instead of captured input
4. Non-blocking - Returns control immediately after rendering

State Management

Tables skip the normal prompt lifecycle states:

State	Interactive Prompts	Table Prompts
initial	✓ Initial render	✗ Skipped
active	✓ User input loop	✗ Skipped
error	✓ Validation failures	✗ Never used
submit	✓ Final render	✓ Only state
cancel	✓ User cancellation	✗ Not applicable

The table immediately transitions to submit state at src/Table.php59 bypassing the interactive lifecycle documented in The Prompt Lifecycle.

Sources: src/Table.php55-64

---

Integration with Prompt System

Inheritance from Base Prompt

Despite being non-interactive, Table extends Prompt to leverage infrastructure:

Inherited Functionality:

1. Output Management - Uses static::output() for buffered writing
2. Theme Delegation - Calls $this->renderTheme() to delegate to TableRenderer
3. Terminal Spacing - Calls capturePreviousNewLines() for proper formatting
4. State Property - Uses $this->state for renderer state matching

Sources: src/Table.php9-73

The value() Method

Tables implement value() to satisfy the Prompt contract, but always return true:

Location: src/Table.php69-72

This return value is not meaningful for display components - tables produce no user input. The method exists to maintain consistency with the Prompt interface.

Sources: src/Table.php69-72

---

Theme Rendering

Renderer Delegation

Tables delegate visual presentation to theme-specific renderers through the renderTheme() method inherited from Prompt. The renderer is responsible for:

1. Formatting column headers
2. Drawing table borders and separators
3. Aligning cell contents
4. Applying colors and styling
5. Handling terminal width constraints

The actual rendering implementation lives in theme-specific renderer classes (e.g., TableRenderer), documented in Prompt-Specific Renderers.

Renderer State Handling

The renderer's __invoke() method receives the Table instance and its state. For tables, the state is always 'submit':

Since tables only use the submit state, renderers don't need to handle active, error, or cancel states like interactive prompts do.

Sources: src/Table.php59-61

---

Usage Examples

Basic Table with Headers

Table Without Headers

Using Collections

Programmatic Table Creation

Sources: src/Table.php1-73 src/helpers.php220-231

---

Summary

The Table component provides a simple, declarative API for displaying structured data:

Aspect	Implementation
Helper Function	table($headers, $rows) at src/helpers.php227
Class	Table extends Prompt at src/Table.php9
Data Format	Arrays or Collections of strings/arrays
Display Method	display() or prompt()
Return Value	Always true (non-interactive)
State	Immediately transitions to 'submit'
Rendering	Delegates to theme-specific TableRenderer

Tables integrate with the Prompt system architecture while maintaining a simplified lifecycle appropriate for display-only components. For interactive data selection, use Selection Prompts or Search Prompts instead.

Sources: src/Table.php1-73 src/helpers.php220-231