PHPackages                             abcarroll/simple-ansi-escape - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [CLI & Console](/categories/cli)
4. /
5. abcarroll/simple-ansi-escape

ActiveLibrary[CLI & Console](/categories/cli)

abcarroll/simple-ansi-escape
============================

Intuitively use ANSI escape sequences to add color and formatting to your php-cli scripts

v1.0(10y ago)5803BSDPHPPHP >=5.5.0

Since Jun 28Pushed 9y ago1 watchersCompare

[ Source](https://github.com/abcarroll/simple-ansi-escape)[ Packagist](https://packagist.org/packages/abcarroll/simple-ansi-escape)[ Docs](http://github.com/abcarroll/simple-ansi-escape)[ RSS](/packages/abcarroll-simple-ansi-escape/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)DependenciesVersions (3)Used By (0)

Simple ANSI Escape
==================

[](#simple-ansi-escape)

Using ANSI escape codes, you can add color and formatting to terminals used by php5-cli. Simple-Ansi-Escape is a simple class to turn the arcane ANSI escape codes into friendly aliases that are easy to remember.

Simple-Ansi-Escape tries to be intuitive as possible and is very flexible in its parameters. As the name implies, it is also very simple. There is only one class definition that contains one static public method, `ansiEscape()`. Simple-Ansi-Escape supports most standard ANSI escape codes and some nonstandard ones. It does not, however, support xterm-256 extensions (yet).

Simple Usage
------------

[](#simple-usage)

A separate, more in-depth and hands-on tutorial is distributed with the repository, see `extras/tutorial.php`. Run it, and read the source code.

There is a single class, `SimpleAnsiEscape` that defines one static public function, `SimpleAnsiEscape::ansiEscape()`. If you are using a PSR-4 compatible auto-loader, you can get started with some gaudy yellow blinking text with just two lines:

```
use SimpleAnsiEscape\SimpleAnsiEscape as esc;
echo esc::ansiEscape('color/yellow, blink', "I hope you enjoy Simple-Ansi-Escape!");
```

The full prototype is, in namespace `SimpleAnsiEscape`:

```
SimpleAnsiEscape::ansiEscape( [ array|string $formatting, [ $wrapAround = null ] ] )
```

`::ansiEscape()` tries to be very flexible in what you pass it. The first parameter can be either an array with one or more array elements, or a string. In its array form, each array element should correspond to a single *escape alias* such as "color/yellow" in the previous example. In its string form, you can pass comma-, space- or semicolon-delimited *escape aliases*. Examples:

```
// In the array form, one-parameter syntax:
echo esc::ansiEscape(array('color/blue', 'faint', 'underline')), "I hope you enjoy Simple-Ansi-Escape!");

// The same thing, as a string:
echo esc::ansiEscape('color/blue, faint, underline', "I hope you enjoy Simple-Ansi-Escape!");

// You can use commas, spaces, or semi-colons as well.  Although it looks poor, even
// mixing and matching will not confuse Simple-Ansi-Escape:
echo esc::ansiEscape('color/red faint; underline, bold', "I hope you enjoy Simple-Ansi-Escape!");
```

With no parameters, it is synonymous with `::ansiEscape('reset')`` and will reset all open-ended formatting.

You can also use `::ansiEscape()` with a single parameter to output only the escape codes. When called with a single parameter, no ANSI reset is called automatically. While you need to call reset yourself (by calling `::ansiEscape()`with no parameters), but it makes nesting a lot easier:

Note that you cannot nest within the same function call, but it's easy to nest using a couple of extra calls:

```
// This is INCORRECT.  The inner escape will terminate formatting and ' properly' will be
// in the default terminal style.
echo esc::ansiEscape(
    'text/green',
    "This is NOT how you " . esc::ansiEscape('bold', 'nest') . " properly!"
);

// This is CORRECT.  We're build the value in the proper linear order:
echo esc::ansiEscape('text/green') . "This is how you ". esc::ansiEscape('bold')
    . "properly " . esc::ansiEscape('~bold') . "next formatting." . esc::ansiEscape();
```

### Always reset

[](#always-reset)

A final note: when using ANSI escape codes, you are sending tiny textual sequences that are interpreted by your terminal. The terminal has no knowledge of when php5-cli terminates; therefore, you must ensure you do not have any open-ended escape codes, or your formatting will spill out into the terminal, even after your script terminates.

If you have a colorful `PS1` shell environmental variable, you *may* not notice this, so please be mindful. During development, if you make a mess of your terminal, simply run the `reset` shell command to start over fresh.

Formatting Syntax, Names
------------------------

[](#formatting-syntax-names)

You can use the characters `~`, `!` or `^` for negate. For example `~bold`, `!bold` and `^bold` are all equivalent in that they remove bold formatting. Not all sequences can be negated. Background and text use 'bg/default', and 'color/default' to reset back to defaults. For those that do not have a negate syntax, you must simply send an ANSI reset.

Escape Aliases
--------------

[](#escape-aliases)

Escape aliases are the heart of AnsiEscape. There is a supplied script, in `extras/printEscAliases.php` which will print a table much like the ones below, and show demo typeset instead so you can test your terminal's capabilities.

### Most important (compatible) escape aliases are seen in the table below.

[](#most-important-compatible-escape-aliases-are-seen-in-the-table-below)

Escape AliasNotesresetAll formatting reset to baseline.text/defaultChange text (foreground) color to default. Negate any previously set color.text/blackChange text (foreground) color to black. Alias color/black.text/blueChange text (foreground) color to blue. Alias color/blue.text/cyanChange text (foreground) color to cyan. Alias color/cyan, color/lightblue.text/greenChange text (foreground) color to green. Alias color/green.text/magentaChange text (foreground) color to magenta. Alias color/magenta, color/pink.text/redChange text (foreground) color to red.text/whiteChange text (foreground) color to white.text/yellowChange text (foreground) color to yellow.bg/defaultChange text (foreground) color default. Negate any previously set background color.bg/blackChange background color to black.bg/blueChange background color to blue.bg/cyanChange background color to cyan. Alias bg/lightblue.bg/greenChange background color to green.bg/magentaChange background color to magenta. Alias bg/pink.bg/redChange background color to red.bg/whiteChange background color to white.bg/yellowChange background color to yellow.blinkSets the text to a blink. xterm and many terminals support this, but not all.~blinkBlink off.boldSets the text to bold typeface.~boldReturns the text to normal intensity. Same code as ~faint.concealConceals text. Sets text and background to the same as used by terminal.~concealReveals text. Alias for '~reveal'.revealReveals text. Alias for '~conceal'.~revealConceals text. Alias for 'conceal'.crossedStrike-through text. Well supported.~crossedNot strike-through text.faintFaint / dim text.~faintReturns to the text to normal intensity. Same code as ~bold.italicItalics typeface. Not as well supported as most, but supported by xterm.~italicNot italics or fraktor. Same code as ~fraktor.negativeInverts background and foreground (text) color.~positiveAlias for negative - negate positive.~negativeAlias for positive - negate negative.positiveReturns background from inversion.overlineOverline over text. Not as well supported.~overlineNot overlined.underlineUnderline text.~underlineNot underline or double underline. Use to negate double underline as well.### Lesser Supported and Non-Standard Escape Codes

[](#lesser-supported-and-non-standard-escape-codes)

These are escape codes that I've never seen work in a modern terminal. You may have better luck.

Escape AliasNotesblinkfastblinkslowIn xterm, this will cause a blink but at the exact same rate as standard blink.~~boldThis is a variant for bold off (21) which isn't as widely supported.dblunderlineencircle~encirclefont/0I've never seen any of these fonts work in xterm.font/1font/2font/3font/4font/5font/6font/7font/8font/9font/defaultResets font to default, if you could get it to change to begin with.frakturI had this work on one terminal before, it's a gothic style font. Alias for gothic.~frakturNot fraktor, alias for ~gothic. Also will stop italics.frame~frameLicense
-------

[](#license)

The code is licensed under the 2-clause BSD license.

###  Health Score

29

—

LowBetter than 59% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity16

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

3978d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/13ac690f7dcc7b9e3f0bea11ac63032685475b78c7dcfeeaa69b6e64f1c0e5a7?d=identicon)[abcarroll](/maintainers/abcarroll)

---

Top Contributors

[![abcarroll](https://avatars.githubusercontent.com/u/961513?v=4)](https://github.com/abcarroll "abcarroll (23 commits)")

---

Tags

php-cliansi

### Embed Badge

![Health badge](/badges/abcarroll-simple-ansi-escape/health.svg)

```
[![Health](https://phpackages.com/badges/abcarroll-simple-ansi-escape/health.svg)](https://phpackages.com/packages/abcarroll-simple-ansi-escape)
```

###  Alternatives

[adhocore/cli

Command line interface library for PHP

3501.2M50](/packages/adhocore-cli)[clue/term-react

Streaming terminal emulator, built on top of ReactPHP.

10410.2M2](/packages/clue-term-react)[alecrabbit/php-console-spinner

Extremely flexible spinner for \[async\] php cli applications

24032.0k2](/packages/alecrabbit-php-console-spinner)[bvanhoekelen/terminal-style

Return your terminal message in style! Change the text style, text color and text background color form the terminal interface with ANSI color codes. The terminal style tool support Laravel and Composer.

19784.4k2](/packages/bvanhoekelen-terminal-style)[alecrabbit/php-cli-snake

Lightweight cli spinner with zero dependencies

29211.3k5](/packages/alecrabbit-php-cli-snake)[malenki/ansi

Simple class to put some colors into your CLI PHP apps!

4345.0k1](/packages/malenki-ansi)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)