bebat / console-color
Apply colors & styles to text for command line output
Installs: 1 044
Dependents: 0
Suggesters: 0
Security: 0
Stars: 3
Watchers: 1
Forks: 0
Open Issues: 2
Requires
- php: ^8.1
Requires (Dev)
- bebat/verify: ~3.1.1
- captainhook/captainhook: ~5.16.4
- captainhook/plugin-composer: ~5.3.3
- ergebnis/composer-normalize: ~2.33.0
- friendsofphp/php-cs-fixer: ^3.21.1
- maglnet/composer-require-checker: ~4.6.0
- mockery/mockery: ~1.6.2
- phpstan/extension-installer: ~1.3.1
- phpstan/phpstan: ~1.10.25
- phpstan/phpstan-deprecation-rules: ~1.1.3
- phpstan/phpstan-mockery: ~1.1.1
- phpstan/phpstan-phpunit: ~1.3.13
- phpstan/phpstan-strict-rules: ~1.5.1
- phpunit/phpunit: ~10.2.4
- zalas/phpunit-globals: ~3.1.2
This package is auto-updated.
Last update: 2024-10-26 23:32:36 UTC
README
Console Color is a lightweight PHP 8.1+ library for adding color & other styles to text in the command line.
Installation
The Console Color library can be installed via Composer:
composer require bebat/console-color
Basic Usage
To apply style to a text you need an instance of BeBat\ConsoleColor\Style
. With that you can apply a style object to some text:
use BeBat\ConsoleColor\Style; $style = new Style(); echo $style->apply('This text is green', Style\Color::Green) . PHP_EOL;
The Style
class will try to determine if console output can be styled automatically (more details on this can be found in the Environment Variables section below). By default, it looks at STDOUT
and checks if it is a TTY. If you are using a different output type (such as a php://
I/O stream) you may pass that to Style()
to have it determine if that stream supports styling:
use BeBat\ConsoleColor\Style; $handle = fopen($something, 'w'); $style = new Style($handle); fwrite($handle, $style->apply( 'If $something points to a console this text will have a cyan background. ' . 'Otherwise it will just be plain.', Style\BackgroundColor::Cyan, ));
You may use the force()
method to make Style
always apply styles to text, regardless of whether it thinks the output resource supports it:
use BeBat\ConsoleColor\Style; $handle = fopen($something, 'w'); $style = new Style($handle); $style->force(); fwrite($handle, $style->apply( 'This text will always have styling applied to it.', Style\Text::Bold, ));
Environment Variables
In addition to checking if STDOUT
is a TTY, Style
will look at several environment variables to determine if styles should be applied, and what level of support the user's terminal has for styles.
FORCE_COLOR
- If the user has setFORCE_COLOR
styling will be applied, even ifStyle
doesn't think the output is a TTY.NO_COLOR
- If the user has setNO_COLOR
styling will be disabled.NO_COLOR
takes precedence overFORCE_COLOR
.TERM
-Style
will checkTERM
to see if it supports 256 colors.COLORTERM
- IfCOLORTERM
is set totruecolor
thenStyle
will apply RGB based colors.
Included Styles
Style::apply()
accepts an instance of StyleInterface
, and Console Color includes a number of styles that implement this interface.
To see what styles your terminal supports and what they look like, run the included sample.php
file.
Basic Styles
Style\Text
, Style\Underline
, Style\Color
, and Style\BackgroundColor
are backed enumerations which helps to make Console Color's API extremely clean. These styles have the broadest support in most terminals (with some exceptions).
Text
Style\Text::None
- no styleStyle\Text::Bold
- bold text (may also "brighten" the color in some terminals)Style\Text::Faint
- dim text colorStyle\Text::Italic
- italicsStyle\Text::Underline
- underlineStyle\Text::Blink
- blinking text (use wisely 😉)Style\Text::Reverse
- swap foreground and background colorsStyle\Text::Concealed
- hides the text (it is still present and can be selected)Style\Text::Strike
- strikethrough, not supported in all terminalsStyle\Text::DoubleUnderline
- double or bold underline, not supported in all terminalsStyle\Text::Overline
- line over text, not supported in all terminalsStyle\Text::Superscript
- superscript text, rarely supportedStyle\Text::Subscript
- subscript text, rarely supported
Underline
Custom underline styles are not widely supported but some terminals do include them. Most, if not all, will fall back on just displaying a single underline.
Style\Underline::Single
Style\Underline::Double
Style\Underline::Wavy
Style\Underline::Dotted
Style\Underline::Dashed
Foreground & Background Color
Style\Color
and Style\BackgroundColor
both support the same values and have an identical API.
Style\Color::Black
Style\Color::Red
Style\Color::Green
Style\Color::Yellow
Style\Color::Blue
Style\Color::Magenta
Style\Color::Cyan
Style\Color::White
Style\Color::Default
Style\Color::BrightBlack
Style\Color::BrightRed
Style\Color::BrightGreen
Style\Color::BrightYellow
Style\Color::BrightBlue
Style\Color::BrightMagenta
Style\Color::BrightCyan
Style\Color::BrightWhite
256 & True Color
Most terminal programs support 256 color output, and many now also support 24-bit "true" colors. Console Color can apply those colors to the foreground, background, or underline color through the Style\Color256
and Style\ColorRGB
classes.
Style\Color256::foreground(int $code)
- apply a 256 color to the textStyle\Color256::background(int $code)
- apply a 256 color to the backgroundStyle\Color256::underline(int $code)
- apply a 256 color to an underline (see composite styles below)Style\ColorRGB::foreground(int $red, int $green, int $blue)
- apply an RGB color to the textStyle\ColorRGB::background(int $red, int $green, int $blue)
- apply an RGB color to the backgroundStyle\ColorRGB::underline(int $red, int $green, int $blue)
- apply an RGB color to an underline (see composite styles below)
Composite Styles
It's possible to apply more than one style to your text by using the Style\Composite()
class. For example, to apply color to both the foreground and background:
use BeBat\ConsoleColor\Style; $style = new Style(); echo $style->apply( 'This text is white on red', new Style\Composite(Style\Color::BrightWhite, Style\BackgroundColor::Red), ) . PHP_EOL;
Style\Composite()
is also required if you want to add color to an underline:
use BeBat\ConsoleColor\Style; $style = new Style(); echo $style->apply( 'This text has a typo', new Style\Composite(Style\Underline::Wavy, Style\ColorRGB::underline(255, 0, 0)), ) . PHP_EOL;
Style\Composite()
can actually take as many styles as you need to apply:
use BeBat\ConsoleColor\Style; $style = new Style(); echo $style->apply( "Please don't do this\n", new Style\Composite( Style\Text::Bold, Style\Text::Italic, Style\Text::Blink, Style\Color256::background(34), Style\Color256::foreground(227), ), );