testomat / terminal-colour
Return your terminal message in style! Change the text style, text color and text background color from the terminal, console or shell interface with ANSI color codes.
Fund package maintenance!
prisis
Requires
- php: ^7.3
- thecodingmachine/safe: ^1.1.0
Requires (Dev)
- ext-json: *
- phpunit/phpunit: ^9.0.2
- dev-master / 1.1.x-dev
- 1.1.1
- 1.1.0
- 1.0.0
- dev-dependabot/npm_and_yarn/json5-2.2.3
- dev-dependabot/npm_and_yarn/minimist-1.2.6
- dev-dependabot/npm_and_yarn/node-fetch-2.6.7
- dev-dependabot/npm_and_yarn/path-parse-1.0.7
- dev-dependabot/composer/phpunit/phpunit-tw-9.5.8
- dev-dependabot/npm_and_yarn/textlint-12.0.2
- dev-dependabot/npm_and_yarn/hosted-git-info-2.8.9
- dev-dependabot/add-v2-config-file
- dev-dependabot/composer/dot-build/wikimedia/composer-merge-plugin-tw-2.0.1
- dev-dependabot/npm_and_yarn/lodash-4.17.21
- dev-dependabot/npm_and_yarn/write-good-1.0.8
- dev-dependabot/npm_and_yarn/textlint-rule-terminology-2.1.5
- dev-dependabot/npm_and_yarn/ini-1.3.8
- dev-dependabot/npm_and_yarn/ini-1.3.7
- dev-dependabot/npm_and_yarn/textlint-rule-en-capitalization-2.0.3
- dev-dependabot/composer/thecodingmachine/safe-tw-1.3.3
- dev-feature/template/sync/narrowspark/php-library-template
- dev-dependabot/npm_and_yarn/node-fetch-2.6.1
- dev-dependabot/npm_and_yarn/textlint-rule-alex-3.0.0
- dev-dependabot/npm_and_yarn/dot-prop-4.2.1
- dev-dependabot/npm_and_yarn/textlint-rule-no-dead-link-4.7.0
This package is auto-updated.
Last update: 2024-03-05 12:30:21 UTC
README
- The easiest way to style your text in the command line / terminal
- Change text color to red, green, yellow ...
- Change background color to red, green, yellow ...
- Change text style to bold, dim, underlined, blink ...
- Has support for 0 , 16, 256 and true color ...
Installation
Run
$ composer require testomat/terminal-colour
Note : By default, the Windows command console doesn’t support output coloring. This library disables output coloring for Windows systems. But if your commands or scripts invoke other scripts which emit color sequences, they will be wrongly displayed as raw escape characters. Install the Cmder, ConEmu, ANSICON or Mintty (used by default in GitBash and Cygwin) to add coloring support to your Windows command console.
Usage
Using Color Styles
<?php declare(strict_types=1); use Testomat\TerminalColour\Formatter; $formatter = new Formatter(); // green text $formatter->format('<info>foo</info>'); // yellow text $formatter->format('<comment>foo</comment>'); // black text on a cyan background $formatter->format('<question>foo</question>'); // white text on a red background $formatter->format('<error>foo</error>');
The closing tag can be replaced by </>
, which revokes all formatting options established by the last opened tag.
It’s possible to define your own styles using the Formatter class:
<?php declare(strict_types=1); use Testomat\TerminalColour\Formatter; use Testomat\TerminalColour\Style; $style = new Style('red', 'yellow', ['bold', 'blink']); $formatter = new Formatter(false, ['fire' => $style]); $formatter->format('<fire>foo</fire>');
Available foreground and background colors are black, red, green, yellow, blue, magenta, cyan, white, default, dark_grey, light_grey, light_red, light_green, light_yellow, light_blue, light_magenta, light_cyan, light_white
.
And available options are: none, bold, dark, italic, underscore, blink, blink_fast, crossed_out, double_underline, curly_underline, overlinem, reverse
(enables the "reverse video" mode where the background and foreground colors are swapped) and conceal
(sets the foreground color to transparent, making the typed text invisible—although it can be selected and copied; this option is commonly used when asking the user to type sensitive information).
You want to use 256 colors
or true colors
than you must use the StyleCode
class.
<?php declare(strict_types=1); use Testomat\TerminalColour\Formatter; use Testomat\TerminalColour\StyleCode; $style256 = new StyleCode(34); // will be transformed to '38;5;34' blue $trueStyle = new StyleCode("38;2;1;1;1"); // same goes for 1;1;1 as value; will be transformed to '38;2;1;1;1' $formatter = new Formatter(false, ['color256Blue' => $style256, 'trueColor' => $trueStyle]); $formatter->format('<color256Blue>foo</color256Blue>');
You can also set these colors and options directly inside the tag name:
// green text $formatter->format('<fg=green>foo</>'); // black text on a cyan background $formatter->format('<fg=black;bg=cyan>foo</>'); // bold text on a yellow background $formatter->format('<bg=yellow;options=bold>foo</>'); // bold text with underscore $formatter->format('<options=bold,underscore>foo</>');
Note: if you need to render a tag literally, escape it with a backslash: <info> or use the escape() method to escape all the tags included in the given string.
You have the possibility with formatAndWrap(string $message, int $width)
function to wrap you text to a specific width, 0 means no wrapping.
Note: you want to check the color support for you terminal check the example folder out.
Displaying Clickable Links
Commands can use the special <href>
tag to display links like the <a>
elements of web pages:
$formatter->format('<href=https://narrowspark.com>Narrowspark Homepage</>');
If your terminal belongs to the list of terminal emulators that support links you can click on the "Narrowspark Homepage" text to open its URL in your default browser. Otherwise, you’ll see "Narrowspark Homepage" as regular text and the URL will be lost.
Terminal Util
You want to know, what color or how any columns your terminal supports, than you can call:
<?php declare(strict_types=1); use Testomat\TerminalColour\Util; echo Util::getNumberOfColumns(); // returns the number of the columns echo Util::getSupportedColor(); // returns the supported color as int
Links
Hyperlinks (a.k.a. HTML-like anchors) in terminal emulators
Versioning
This library follows semantic versioning, and additions to the code ruleset are performed in major releases.
Changelog
Please have a look at CHANGELOG.md
.
Contributing
Please have a look at CONTRIBUTING.md
.
Code of Conduct
Please have a look at CODE_OF_CONDUCT.md
.
License
This package is licensed using the MIT License.
Please have a look at LICENSE.md
.