Download the PHP package tflori/hugga without Composer

tflori/hugga

PHP library for console applications. It supports formatting of messages and tables as well input handling with choices.

Installation

Like all my libraries: only with composer

Basic usage

Usage

Create a Console instance and use it throughout your application. All input and output goes through this object.

Writing output

line() writes a message followed by a newline. write() writes without a newline. Both accept an optional weight (verbosity level) as the second argument — output below the current verbosity threshold is silently dropped.

Convenience methods apply a predefined style and write to the appropriate stream:

Formatting

Embed format tags using ${...} syntax anywhere in a string. Reset all formatting with ${r} or ${reset}.

Available attributes: color names (red, green, cyan, yellow, blue, magenta, white, grey, …), bold / b, underline / u, fg:<color>, bg:<color>.

Deleting output

Remove recently written text without leaving a blank line:

Asking questions

Pass a string for a free-text prompt (optional default value as second argument):

Use Confirmation for yes/no questions — returns true or false:

Use Choice to let the user pick from a list. With an associative array the key is returned by default:

In an interactive terminal the choice is navigated with cursor keys. Chain methods to customise behaviour:

Tables

Pass the data rows and an optional header row to Table, then call draw():

Chain options to customise the appearance before drawing:

Progress bars

Provide the total number of steps (or null for an indeterminate spinner) and call start(). Call advance() inside your loop and finish() when done:

Multiple progress bars can run concurrently — each one stays pinned to the bottom of the output while regular log lines scroll above it. Pass null as the total for an indeterminate throbber:

Reading raw input

Observing keyboard input

getInputObserver() gives direct, non-echoed access to individual key presses:

Full reference

See the API reference for the complete method list, or run the bundled demo:

A paginated-table example is in examples/paginated-table.php.

Features

Some features are still planned but a lot of features are available and they are enough for start and replacing symfony/console.

Output Handling

• Drawings: a mechanism to stay at the end of your output while other output is printed above (clocks, progress bars etc.)
• Weighted output: just output and hugga will handle if the user want's to see it or not (verbosity)
• Formatting output: easy formatting with combined expression (example: ${red;bold}text${r})
• Output tables: easy to use tables with a lot of formatting features:
  • Predefined format: configure the formatting once and for all later tables
  • Borders: enable or disable borders (borders inside: between rows)
  • Padding: left and right padding inside cells
  • Repeat headers: repeat headers every nth row
  • Header style: define styles used for headers
• Progress bars: smooth progress bars with 8 steps (utf-8) and other formatting features:
  • Undetermined: throbber that spins between edges
  • Update rate: instead of define after how much steps the progressbar should update (symfony/console) you define how much time has to elapse before redrawing
  • Characters: change the characters used for the progress bar
  • Throbber: change the throbber used for undetermined progress bar
  • Floating point steps: use floating point numbers

Input Handling

• InputObserver: directly access the keyboard without writing the output to console
• EditLine fix: edit line (replacement for read line) can not read single key presses
• ReadLine: use read line for reading from stdin if available
• Read chars: read a specific amount of characters (multibyte safe)
• Read until: read input until a specific string appears (example: \n.\n)
• Simple question: a simple question with default value
• Confirmation: a question with the choice between y(es) and n(o) (characters can be changed)
• Choice: a question to choose between a list of options
  • Interactive by default: choose with cursor keys and select with enter using InputObserver
  • Return key: return the key instead of the value (default for assoc arrays)
  • Limit: change the limit of visible options (for interactive version)

Planned features

• Debug output: output variables in a human readable format with highlighting
• Interactive tables: scroll through tables using cursor keys and pagination