PHP Luminova: Command Outputs Formatting Using the Text Utils

The Luminova Text Utils class is a powerful feature of the Luminova Framework's command-line tooling. It enhances the appearance of your output text, elevating your CLI tool with elegance and professionalism. Whether you want to beautify your output for end users or improve readability during development, Text Utils offers a range of functions to help you achieve your goals.

This class provides static methods for applying various text styles, including color, effects, and background colors, using ANSI codes for terminal output. You can style text similarly to how you would with HTML and CSS. Additionally, it provides a block layout method, allowing you to create structured designs similar to an HTML DIV. With this method, you can customize text positioning, add borders (including border color and radius), apply shadow effects, and set font colors and styles.

Usage Examples

An example string content.

<?php
$string = sprintf("%s\n%s\n%s\n%s",
    'This is a Title',
    'This is the body of the console message. It contains a detailed explanation of long content content.',
    'Here is some additional medium-length content.',
    'Current Time: ' . date('Y-m-d H:i:s')
);

Creating a Block Layout:

In this example, we use the Text::block method to format the string within a styled block.

<?php
use Luminova\Command\Terminal;

$block = Text::block(
    $string, 
    Text::LEFT, 
    1, 
    'white',
    'green',
    Text::NO_FONT,
    Text::BORDER_THICKER | Text::BORDER_RADIUS,
    'red',
    'cyan'
);

Terminal::writeln($block);

Output:

╭━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╮
┃                                                                                                      ┃
┃ This is a Title                                                                                      ┃
┃ This is the body of the console message. It contains a detailed explanation of long content content. ┃
┃ Here is some additional medium-length content.                                                       ┃
┃ Current Time: 2024-10-29 13:52:52                                                                    ┃
┃                                                                                                      ┃
╰━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╯

Inline Text Formatting:

This example demonstrates how to format the string in an inline style, aligning it to the right with specific text styles.

<?php
$inline = Text::inline(
    $string,
    Text::RIGHT, 
    'white',
    'red',
    Text::FONT_UNDERLINE | Text::FONT_ITALIC
);

Terminal::writeln($block);

Output:

                                                                                                                   This is a Title
                              This is the body of the console message. It contains a detailed explanation of long content content.
                                                                                    Here is some additional medium-length content.
                                                                                                 Current Time: 2024-10-29 13:37:29

Plain Text Formatting:

In this example, the Text::plain method is used to display the string content centered with underline and italic effects.

$plain = Text::plain(
    $string,
    Text::CENTER,
    Text::FONT_UNDERLINE | Text::FONT_ITALIC
);
Terminal::writeln($plain);

Output:

                                    This is a Title                                                                         
This is the body of the console message. It contains a detailed explanation of long content content.                                                         
                    Here is some additional medium-length content.                                                                                     
                            Current Time: 2024-10-29 13:37:29                                                 

Outputs Visual Representation

Here's how the output appears visually in a terminal:

Class Definition

• Class namespace: \Luminova\Command\Utils\Text

Constants

Each constant provides a specific visual or positional styling option to modify text appearance and layout dynamically.

Methods

block

Create a block of text with optional padding, colors, and alignment.

public static block(
  string $text, 
  int $position = self::LEFT, 
  int $padding = 0, 
  ?string $foreground = null, 
  ?string $background = null, 
  int $fonts = self::NO_FONT, 
  int $borders = self::NO_BORDER, 
  ?string $borderColor = null, 
  ?string $shadow = null
): string

Parameters:

Return Value:

string - Return the formatted block layout, with text content.

card

Create a card-like layout with optional formatting and alignment.

public static card(
  string $text, 
  int $position = self::LEFT, 
  int $padding = 0, 
  ?string $foreground = null, 
  ?string $background = null, 
  int $fonts = self::NO_FONT, 
  int $borders = self::BORDER
): string

Parameters:

Return Value:

string - Return the formatted card block, with text content.

inline

Create an inline text with optional colors, and alignment.

public static inline(
  string $text, 
  int $position = self::LEFT, 
  ?string $foreground = null, 
  ?string $background = null, 
  int $fonts = self::NO_FONT
): string

Parameters:

Return Value:

string - Return the formatted inline text block.

plain

Create plain text with optional font styles and alignment.

public static plain(string $text, int $position = self::LEFT, int $fonts = self::NO_FONT): string

Parameters:

Return Value:

string - Return the formatted plain text text with the applied alignment and optional font styles.

marquee

Displays a scrolling marquee effect for the given text in the terminal.

The text scrolls based on the specified speed, direction, and repeat count,with optional ANSI styling for foreground, background, and font.

public static marquee(
  string $text, 
  int $speed, 
  int $direction = self::LEFT, 
  int $repeat = 1, 
  ?string $foreground = null, 
  ?string $background = null, 
  int $fonts = self::NO_FONT
): void

Parameters:

flash

Displays a flashing effect for the given text in the terminal for a specified duration.

The text alternates between visible and hidden at the defined speed, with optionalANSI styling for foreground, background, and font.

public static flash(
  string $text, 
  int $duration = 3, 
  int $speed = 500000, 
  ?string $foreground = null, 
  ?string $background = null, 
  int $fonts = self::NO_FONT
): void

Parameters:

style

Applies specified ANSI font styles to the provided text.

This method allows for multiple font styles to be combined using bitwise operators,such as Text::FONT_BOLD | Text::FONT_ITALIC. If no valid font style is specifiedor if the text already contains ANSI codes, the original text is returned unmodified.

public static style(string $text, int $fonts): string

Parameters:

Return Value:

string - Return the styled text with ANSI codes applied, or the original text if no valid styles are given.

wrap

Wraps the given text to a specified maximum width, applying padding on all sides.

The text is wrapped based on the maximum width, and optional padding can be appliedto the left, right, top, and bottom of the text block.

public static wrap(string $text, int $width, int $left, int $right, int $top, int $bottom): string

Parameters:

Return Value:

string - Return the padded wrapped text.

fit

Pads a string to fit a specified length by adding spaces.

This method takes a string and pads it with spaces to ensure that it reaches adefined maximum length. It allows for additional space at the end of the stringand an optional indent at the beginning.

public static fit(string $text, int $max, int $extra = 2, int $indent): string

Parameters:

Return Value:

string - Returns the padded string, ensuring it meets the specified length.

strlen

Calculate the character length of a string, ignoring any applied ANSI color or style codes.

This method removes any ANSI color codes from the text before calculating its length,ensuring that only the visible characters are counted.

public static strlen(string $string, string $encoding = 'UTF-8'): int

Parameters:

Return Value:

int - Return the number of visible characters in the string.

length

Calculate the length of ANSI formatting codes applied to a given text.

This method returns the total length (in characters) of ANSI codes used to applycolor or style formatting, based on the specified fonts, foreground, and background.

public static length(?int $fonts = null, ?string $foreground, ?string $background = null): int

Parameters:

Return Value:

int - Return the total length of ANSI formatting characters included.

height

Calculate the height of a string based on the number of lines (newline).

public static height(string $text): int

Parameters:

Return Value:

int - Return the total number of lines in the text.

largest

Finds the longest line from a multi-line text string, that may contain various newline formats.

public static largest(string $text): array<int,mixed>

Parameters:

Return Value:

array{0: string, 1: int} - Returns an array containing the longest line.

• The longest line as the first element.
• Its length as the second element.

Note: Each line is trimmed of leading and trailing whitespace before its length is calculated.

lines

Splits text into an array of lines, normalizing different newline formats.

public static lines(string $text): string[]

Parameters:

Return Value:

array<int,string> - Returns an array of strings, where each string represents a line from the input text.

line

Removes all line breaks (newlines) from the given text and replaces them with an optional specified string.

public static line(string $text, string $replace = ' '): string

Parameters:

Return Value:

string - Returns the processed string with all line breaks replaced by the specified string.If the input text is empty, an empty string is returned.

strip

Removes ANSI escape sequences from the provided text.

This method strips out any ANSI color or formatting codes from the given text,leaving only the plain text content.

public static strip(string $text): string

Parameters:

Return Value:

string - Return the text with all ANSI escape sequences removed.

format

Format and align text with specified padding and alignment, accounting only for visible characters.

This method uses sprintf to align the text based on the specified alignment (left, right, center)and pad it with a chosen character. ANSI codes are ignored in the padding calculation, so the lengthis based on visible characters only.

public static format(string $text, int $padding, int $alignment = self::LEFT, string $char = ' '): string

Parameters:

Return Value:

string - Return the formatted text with applied padding and alignment.

padding

Pads a string on both the left and right sides based on alignment.

public static padding(string $text, int $length, int $alignment = STR_PAD_BOTH, string $char = ' '): string

Parameters:

Return Value:

string - Return the padded string.

margin

Generates a margin with optional horizontal (left and right) padding and border character.

• If $x horizontal (left and right) padding is not provided, it will return a single line with the specifiedborder and character on the right.
• If $x horizontal padding is specified, it will generate multiple lines with the horizontal paddingbetween two border character, repeated for the given number of padding lines.

public static margin(int $padding, string $char = ' ', ?int $horizontal = null): string

Parameters:

Return Value:

string - Return the generated margin with vertical and optional horizontal padding.

font

Retrieves the ANSI escape code for a specific font style.

public static font(int $font): string

Parameters:

Return Value:

string Return the ANSI escape sequence for the specified font style, or an empty string if the font is not recognized.

fonts

Generates the ANSI escape sequence for a combination of font styles, or returns no styling if Text::NO_FONT is specified.

This method constructs a sequence of ANSI codes based on multiple font flags, allowing combined styles.

public static fonts(?int $fonts): string

Parameters:

Return Value:

string - Return the ANSI escape sequence representing the combined font styles, or an empty string if no style is applied.

borders

Determines the border style flags based on the provided border type.

This can be a combination of border styles using bitwise operator,such as Text::BORDER_RADIUS for rounded corners and Text::BORDER_THICKER for a thicker border.Passing Text::NO_BORDER disables borders.

public static borders(?int $borders): array

Parameters:

Return Value:

array{0: bool, 1: bool, 2: bool} - Returns an array with three boolean values:

• [0]: true if any border is enabled, false if NO_BORDER is specified.
• [1]: true if the border has rounded corners (applies BORDER_RADIUS), otherwise false.
• [2]: true if the border is thicker (applies BORDER_THICKER), otherwise false.

corners

Generates the appropriate box-drawing character for borders based on position,corner rounding (radius), and line thickness.

public static corners(string $position = 'topLeft', bool $radius = false, bool $thick = false): string

Parameters:

Return Value:

string - Return the character used to render the box at the given position with the specified style.

Supported Positions Include:

• 'topLeft': Top-left corner.
• 'topRight': Top-right corner.
• 'bottomLeft': Bottom-left corner.
• 'bottomRight': Bottom-right corner.
• 'horizontal': Horizontal edges.
• 'vertical': Vertical edges.
• 'crossings': Intersection or crossing of horizontal and vertical lines.
• 'leftConnector': Left T-connector.
• 'rightConnector': Right T-connector.
• 'topConnector': Top T-connector.
• 'bottomConnector': Bottom T-connector.
• 'topLeftAngle': Angled top-left corner.
• 'topRightAngle': Angled top-right corner.
• 'bottomLeftAngle': Angled bottom-left corner.
• 'bottomRightAngle': Angled bottom-right corner.
• 'plus': A plus sign, often used as a simple intersection.

hasAnsi

Determine if the given text contains ANSI escape sequences.

public static hasAnsi(string $text): bool

Parameters:

Return Value:

bool - Returns true if the text contains ANSI codes, otherwise false.

Dynamic Static Magic Methods

The dynamic static methods allow you to apply fonts and background colors to text using any valid foreground color name as the method.

colorName

Applies the specified color to the text and returns the styled text with ANSI code.

public static {colorName}(
    string $text, 
    ?int $fonts = Text::NO_FONT, 
    ?string $background = null
): string

Parameters:

Return Value:

string - Returns the styled text with the applied ANSI code.

Examples

Applying Text Colors

Styles the text in various colors and returns the styled text with ANSI code.

echo Text::red("Warning: This is an error message!");  // Highlight error messages in red.
echo Text::lightMagenta("This text is light magenta.");  // Output: Styled text in light magenta.
echo Text::white("This text is white.");  // Output: Styled text in white.

Applying Fonts and Background Colors

Styles the text with additional font styles and background colors.

echo Text::red("Critical Error: System failure!", Text::FONT_BOLD | Text::FONT_ITALIC, "white"); 
// Red text with bold, italic fonts and white background.