PHPackages                             asamaru7/ansi-php - 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. asamaru7/ansi-php

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

asamaru7/ansi-php
=================

ANSI Control Functions and ANSI Control Sequences (Colors, Erasing, etc.) for PHP CLI Apps

3.0.3(6y ago)0111MITPHPPHP >=5.4.0

Since Jan 5Pushed 6y agoCompare

[ Source](https://github.com/asamaru7/ansi-php)[ Packagist](https://packagist.org/packages/asamaru7/ansi-php)[ RSS](/packages/asamaru7-ansi-php/feed)WikiDiscussions master Synced 2d ago

READMEChangelog (1)Dependencies (1)Versions (10)Used By (0)

ANSI PHP
========

[](#ansi-php)

[![Build Status](https://camo.githubusercontent.com/97a5ccda89f32718ef5f63f494b7cb6d11f10c92bd069c8e740788a618b2c516/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f6173616d617275372f616e73692d7068702e7376673f7374796c653d666c61742d737175617265)](http://travis-ci.org/asamaru7/ansi-php) [![Source](https://camo.githubusercontent.com/8359962399198cc31a509ccdc6759e4fbd8cf21776c66835e3d5d97a077d6c13/687474703a2f2f696d672e736869656c64732e696f2f62616467652f736f757263652d6173616d617275372f616e73692d2d7068702d626c75652e7376673f7374796c653d666c61742d737175617265)](https://github.com/asamaru7/ansi-php) [![Version](https://camo.githubusercontent.com/e3a96d4e63f1e84253870dfacc0477f1d5f1a960448801329a6a83ab217a14b6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6173616d617275372f616e73692d7068702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/asamaru7/ansi-php) [![Downloads](https://camo.githubusercontent.com/4196e6cf8839c90515c3f52c6de0c43bbd368cad30d60cf198d90db1e9b77b97/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6173616d617275372f616e73692d7068702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/asamaru7/ansi-php/stats) [![License](https://camo.githubusercontent.com/108bc859cccbacb0acb6380dbf50b84de1433781ad4cc58da295e4a2641de179/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6173616d617275372f616e73692d7068702e7376673f7374796c653d666c61742d737175617265)](https://github.com/asamaru7/ansi-php/blob/master/LICENSE)

ANSI Control Functions and ANSI Control Sequences for PHP CLI Apps

Built by Bramus! -

About
-----

[](#about)

`bramus/ansi-php` is a set of classes to working with ANSI Control Functions and ANSI Control Sequences on text based terminals.

- ANSI Control Functions control an action such as line spacing, paging, or data flow.
- ANSI Control Sequences allow one to clear the screen, move the cursor, set text colors, etc.

*(Sidenote: An “ANSI Escape Sequence” is a special type of “ANSI Control Sequence” which starts with the ESC ANSI Control Function. The terms are not interchangeable.)*

Features
--------

[](#features)

When it comes to ANSI Control Functions `bramus/ansi-php` supports:

- `BS`: Backspace
- `BEL`: Bell
- `CR`: Carriage Return
- `ESC`: Escape
- `LF`: Line Feed
- `TAB`: Tab

When it comes to ANSI Escape Sequences `bramus/ansi-php` supports:

- SGR *(Select Graphic Rendition)*: Manipulate text styling (bold, underline, blink, colors, etc.).
- ED *(Erase Display)*: Erase (parts of) the display.
- EL *(Erase In Line)*: Erase (parts of) the current line.

Other Control Sequences – such as moving the cursor – are not (yet) supported.

An example library that uses `bramus/ansi-php` is [`bramus/monolog-colored-line-formatter`](https://github.com/bramus/monolog-colored-line-formatter). It uses `bramus/ansi-php`'s SGR support to colorize the output:

[![Monolog Colored Line Formatter](https://user-images.githubusercontent.com/11269635/28756233-c9f63abe-756a-11e7-883f-a084f35c55e7.gif)](https://user-images.githubusercontent.com/11269635/28756233-c9f63abe-756a-11e7-883f-a084f35c55e7.gif)

Prerequisites/Requirements
--------------------------

[](#prerequisitesrequirements)

- PHP 5.4.0 or greater

Installation
------------

[](#installation)

Installation is possible using Composer

```
composer require asamaru7/ansi-php
```

Usage
-----

[](#usage)

The easiest way to use *ANSI PHP* is to use the bundled `Ansi` helper class which provides easy shorthands to working with `bramus/ansi-php`. The `Ansi` class is written in such a way that you can chain calls to one another.

If you're feeling adventurous, you're of course free to use the raw `ControlFunction` and `ControlSequence` classes.

### Quick example

[](#quick-example)

```
use \Bramus\Ansi\Ansi;
use \Bramus\Ansi\Writers\StreamWriter;
use \Bramus\Ansi\ControlSequences\EscapeSequences\Enums\SGR;

// Create Ansi Instance
$ansi = new Ansi(new StreamWriter('php://stdout'));

// Output some styled text on screen, along with a Line Feed and a Bell
$ansi->color(array(SGR::COLOR_FG_RED, SGR::COLOR_BG_WHITE))
     ->blink()
     ->text('I will be blinking red on a white background.')
     ->nostyle()
     ->text(' And I will be normally styled.')
     ->lf()
     ->text('Ooh, a bell is coming ...')
     ->bell();
```

See more examples further down on how to use these.

Concepts
--------

[](#concepts)

Since v3.0 `bramus/ansi-php` uses the concept of writers to write the data to. By default a `StreamWriter` writing to `php://stdout` is used.

The following writers are provided

- `StreamWriter`: Writes the data to a stream. Just pass in the path to a file and it will open a stream for you. Defaults to writing to `php://stdout`.
- `BufferWriter`: Writes the data to a buffer. When calling `flush()` the contents of the buffer will be returned.
- `ProxyWriter`: Acts as a proxy to another writer. Writes the data to an internal buffer. When calling `flush()` the writer will first write the data to the other writer before returning it.

The `Ansi` helper class functions
---------------------------------

[](#the-ansi-helper-class-functions)

### Core functions:

[](#core-functions)

- `text($text)`: Write a piece of data to the writer
- `setWriter(\Bramus\Ansi\Writers\WriterInterface $writer)`: Sets the writer
- `getWriter()`: Gets the writer

### ANSI Control Function shorthands:

[](#ansi-control-function-shorthands)

These shorthands write a Control Character to the writer.

- `bell()`: Bell Control Character (`\a`)
- `backspace()`: Backspace Control Character (`\b`)
- `tab()`: Tab Control Character (`\t`)
- `lf()`: Line Feed Control Character (`\n`)
- `cr()`: Carriage Return Control Character (`\r`)
- `esc()`: Escape Control Character

### SGR ANSI Escape Sequence shorthands:

[](#sgr-ansi-escape-sequence-shorthands)

These shorthands write SGR ANSI Escape Sequences to the writer.

- `nostyle()` or `reset()`: Remove all text styling (colors, bold, etc)
- `color()`: Set the foreground and/or backgroundcolor of the text. *(see further)*
- `bold()` or `bright()`: Bold: On. On some systems "Intensity: Bright"
- `normal()`: Bold: Off. On some systems "Intensity: Normal"
- `faint()`: Intensity: Faint. *(Not widely supported)*
- `italic()`: Italic: On. *(Not widely supported)*
- `underline()`: Underline: On.
- `blink()`: Blink: On.
- `negative()`: Inverse or Reverse. Swap foreground and background.
- `strikethrough()`: Strikethrough: On. *(Not widely supported)*

**IMPORTANT:** Select Graphic Rendition works in such a way that text styling you have set will remain active until you call `nostyle()` or `reset()` to return to the default styling.

### ED ANSI Escape Sequence shorthands:

[](#ed-ansi-escape-sequence-shorthands)

These shorthands write ED ANSI Escape Sequences to the writer.

- `eraseDisplay()`: Erase the entire screen and moves the cursor to home.
- `eraseDisplayUp()`: Erase the screen from the current line up to the top of the screen.
- `eraseDisplayDown()`: Erase the screen from the current line down to the bottom of the screen.

### EL ANSI Escape Sequence shorthands:

[](#el-ansi-escape-sequence-shorthands)

These shorthands write EL ANSI Escape Sequences to the writer.

- `eraseLine()`: Erase the entire current line.
- `eraseLineToEOL()`: Erase from the current cursor position to the end of the current line.
- `eraseLineToSOL()`: Erases from the current cursor position to the start of the current line.

### Extra functions

[](#extra-functions)

- `flush()` or `get()`: Retrieve contents of a `FlushableWriter` writer.
- `e()`: Echo the contents of a `FlushableWriter` writer.

Examples
--------

[](#examples)

### The Basics

[](#the-basics)

```
// Create Ansi Instance
$ansi = new \Bramus\Ansi\Ansi();

// This will output a Bell
$ansi->bell();

// This will output some text
$ansi->text('Hello World!');
```

*NOTE:* As no `$writer` is passed into the constructor of `\Bramus\Ansi\Ansi`, the default `StreamWriter` writing to `php://stdout` is used.

### Using a `FlushableWriter`

[](#using-a-flushablewriter)

Flushable Writers are writers that cache the data and only output it when flushed using its `flush()` function. The `BufferWriter` and `ProxyWriter` implement this interface.

```
// Create Ansi Instance
$ansi = new \Bramus\Ansi\Ansi(new \Bramus\Ansi\Writers\BufferWriter());

// This will append a bell to the buffer. It will not output it.
$ansi->bell();

// This will append a bell to the buffer. It will not output it.
$ansi->text('Hello World!');

// Now we'll output it
echo $ansi->get();
```

### Chaining

[](#chaining)

`bramus/ansi-php`'s wrapper `Ansi` class supports chaining.

```
// Create Ansi Instance
$ansi = new \Bramus\Ansi\Ansi();

// This will output a Line Feed, some text, a Bell, and a Line Feed
$ansi->lf()->text('hello')->bell()->lf();
```

### Styling Text: The Basics

[](#styling-text-the-basics)

```
$ansi = new \Bramus\Ansi\Ansi();
$ansi->bold()->underline()->text('I will be bold and underlined')->lf();
```

**IMPORTANT** Select Graphic Rendition works in such a way that text styling you have set will remain active until you call `nostyle()` or `reset()` to return to the default styling.

```
$ansi = new \Bramus\Ansi\Ansi();

$ansi->bold()->underline()->text('I will be bold and underlined')->lf();
$ansi->text('I will also be bold because nostyle() has not been called yet')->lf();
$ansi->nostyle()->blink()->text('I will be blinking')->nostyle()->lf();
$ansi->text('I will be normal because nostyle() was called on the previous line');
```

### Styling Text: Colors

[](#styling-text-colors)

Colors, and other text styling options, are defined as contants on `\Bramus\Ansi\ControlSequences\EscapeSequences\Enums\SGR`.

#### Foreground (Text) Colors

[](#foreground-text-colors)

- `SGR::COLOR_FG_BLACK`: Black Foreground Color
- `SGR::COLOR_FG_RED`: Red Foreground Color
- `SGR::COLOR_FG_GREEN`: Green Foreground Color
- `SGR::COLOR_FG_YELLOW`: Yellow Foreground Color
- `SGR::COLOR_FG_BLUE`: Blue Foreground Color
- `SGR::COLOR_FG_PURPLE`: Purple Foreground Color
- `SGR::COLOR_FG_CYAN`: Cyan Foreground Color
- `SGR::COLOR_FG_WHITE`: White Foreground Color
- `SGR::COLOR_FG_BLACK_BRIGHT`: Black Foreground Color (Bright)
- `SGR::COLOR_FG_RED_BRIGHT`: Red Foreground Color (Bright)
- `SGR::COLOR_FG_GREEN_BRIGHT`: Green Foreground Color (Bright)
- `SGR::COLOR_FG_YELLOW_BRIGHT`: Yellow Foreground Color (Bright)
- `SGR::COLOR_FG_BLUE_BRIGHT`: Blue Foreground Color (Bright)
- `SGR::COLOR_FG_PURPLE_BRIGHT`: Purple Foreground Color (Bright)
- `SGR::COLOR_FG_CYAN_BRIGHT`: Cyan Foreground Color (Bright)
- `SGR::COLOR_FG_WHITE_BRIGHT`: White Foreground Color (Bright)
- `SGR::COLOR_FG_RESET`: Default Foreground Color

#### Background Colors

[](#background-colors)

- `SGR::COLOR_BG_BLACK`: Black Background Color
- `SGR::COLOR_BG_RED`: Red Background Color
- `SGR::COLOR_BG_GREEN`: Green Background Color
- `SGR::COLOR_BG_YELLOW`: Yellow Background Color
- `SGR::COLOR_BG_BLUE`: Blue Background Color
- `SGR::COLOR_BG_PURPLE`: Purple Background Color
- `SGR::COLOR_BG_CYAN`: Cyan Background Color
- `SGR::COLOR_BG_WHITE`: White Background Color
- `SGR::COLOR_BG_BLACK_BRIGHT`: Black Background Color (Bright)
- `SGR::COLOR_BG_RED_BRIGHT`: Red Background Color (Bright)
- `SGR::COLOR_BG_GREEN_BRIGHT`: Green Background Color (Bright)
- `SGR::COLOR_BG_YELLOW_BRIGHT`: Yellow Background Color (Bright)
- `SGR::COLOR_BG_BLUE_BRIGHT`: Blue Background Color (Bright)
- `SGR::COLOR_BG_PURPLE_BRIGHT`: Purple Background Color (Bright)
- `SGR::COLOR_BG_CYAN_BRIGHT`: Cyan Background Color (Bright)
- `SGR::COLOR_BG_WHITE_BRIGHT`: White Background Color (Bright)
- `SGR::COLOR_BG_RESET`: Default Background Color

Pass one of these into `$ansi->color()` and the color will be set.

```
use \Bramus\Ansi\ControlSequences\EscapeSequences\Enums\SGR;

$ansi = new \Bramus\Ansi\Ansi();

$ansi->color(SGR::COLOR_FG_RED)
     ->text('I will be red')
     ->nostyle();
```

To set the foreground and background color in one call, pass them using an array to `$ansi->color()`

```
use \Bramus\Ansi\ControlSequences\EscapeSequences\Enums\SGR;

$ansi = new \Bramus\Ansi\Ansi();

$ansi->color(array(SGR::COLOR_FG_RED, SGR::COLOR_BG_WHITE))
     ->blink()
     ->text('I will be blinking red on a wrhite background.')
     ->nostyle();
```

### Using the raw classes

[](#using-the-raw-classes)

As all raw `ControlFunction` and `ControlSequence` classes are provided with a `__toString()` function it's perfectly possible to directly `echo` some `bramus/ansi-php` instance.

```
// Output a Bell Control Character
echo new \Bramus\Ansi\ControlFunctions\Bell();

// Output an ED instruction, to erase the entire screen
echo new \Bramus\Ansi\ControlSequences\EscapeSequences\ED(
    \Bramus\Ansi\ControlSequences\EscapeSequences\Enums\ED::ALL
);
```

To fetch their contents, use the `get()` function:

```
// Get ANSI string for a Bell Control Character
$bell = (new \Bramus\Ansi\ControlFunctions\Bell())->get();

// Get ANSI string for an ED instruction, to erase the entire screen
$eraseDisplay = (new \Bramus\Ansi\ControlSequences\EscapeSequences\ED(
    \Bramus\Ansi\ControlSequences\EscapeSequences\Enums\ED::ALL
))->get();

echo $bell . $bell . $eraseDisplay . $bell;
```

Unit Testing
------------

[](#unit-testing)

`bramus/ansi-php` ships with unit tests using [PHPUnit](https://github.com/sebastianbergmann/phpunit/).

- If PHPUnit is installed globally run `phpunit` to run the tests.
- If PHPUnit is not installed globally, install it locally throuh composer by running `composer install --dev`. Run the tests themselves by calling `vendor/bin/phpunit` or `composer test`

Unit tests are also automatically run [on Travis CI](http://travis-ci.org/bramus/ansi-php)

License
-------

[](#license)

`bramus/ansi-php` is released under the MIT public license. See the enclosed `LICENSE` for details.

ANSI References
---------------

[](#ansi-references)

- [http://en.wikipedia.org/wiki/ANSI\_escape\_code](http://en.wikipedia.org/wiki/ANSI_escape_code)
-
-
- [http://web.mit.edu/gnu/doc/html/screen\_10.html](http://web.mit.edu/gnu/doc/html/screen_10.html)
- [http://www.isthe.com/chongo/tech/comp/ansi\_escapes.html](http://www.isthe.com/chongo/tech/comp/ansi_escapes.html)
-
-
-

###  Health Score

29

—

LowBetter than 60% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity10

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity64

Established project with proven stability

 Bus Factor1

Top contributor holds 88.9% 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

Every ~219 days

Recently: every ~439 days

Total

9

Last Release

2388d ago

Major Versions

1.1.1 → 2.02015-01-06

2.1 → 3.02015-01-07

PHP version history (2 changes)1.0PHP >=5.3.3

2.0PHP >=5.4.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/1003976?v=4)[유영재](/maintainers/asamaru7)[@asamaru7](https://github.com/asamaru7)

---

Top Contributors

[![bramus](https://avatars.githubusercontent.com/u/213073?v=4)](https://github.com/bramus "bramus (40 commits)")[![asamaru7](https://avatars.githubusercontent.com/u/1003976?v=4)](https://github.com/asamaru7 "asamaru7 (4 commits)")[![kovsky0](https://avatars.githubusercontent.com/u/29592430?v=4)](https://github.com/kovsky0 "kovsky0 (1 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/asamaru7-ansi-php/health.svg)

```
[![Health](https://phpackages.com/badges/asamaru7-ansi-php/health.svg)](https://phpackages.com/packages/asamaru7-ansi-php)
```

###  Alternatives

[wp-cli/wp-cli

WP-CLI framework

5.0k17.2M320](/packages/wp-cli-wp-cli)[consolidation/annotated-command

Initialize Symfony Console commands from annotated command class methods.

22569.8M19](/packages/consolidation-annotated-command)[chi-teck/drupal-code-generator

Drupal code generator

26947.8M5](/packages/chi-teck-drupal-code-generator)[seld/cli-prompt

Allows you to prompt for user input on the command line, and optionally hide the characters they type

24725.8M17](/packages/seld-cli-prompt)[illuminate/console

The Illuminate Console package.

12944.1M5.1k](/packages/illuminate-console)[php-tui/php-tui

Comprehensive TUI library heavily influenced by Ratatui

589747.0k6](/packages/php-tui-php-tui)

PHPackages © 2026

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