{"id":13545518,"url":"https://github.com/bramus/ansi-php","last_synced_at":"2025-04-05T06:10:02.897Z","repository":{"id":25398759,"uuid":"28827524","full_name":"bramus/ansi-php","owner":"bramus","description":"ANSI Control Functions and ANSI Control Sequences (Colors, Erasing, etc.) for PHP CLI Apps","archived":false,"fork":false,"pushed_at":"2024-02-19T08:42:39.000Z","size":83,"stargazers_count":89,"open_issues_count":4,"forks_count":10,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-05-17T04:43:55.496Z","etag":null,"topics":["ansi","ansi-colors","ansi-escape-sequences","cli","php"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bramus.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-01-05T19:19:02.000Z","updated_at":"2024-06-18T12:24:50.294Z","dependencies_parsed_at":"2024-06-18T12:24:48.611Z","dependency_job_id":"fcd4abfa-5c41-4b30-8cd7-329239b4780e","html_url":"https://github.com/bramus/ansi-php","commit_stats":{"total_commits":49,"total_committers":5,"mean_commits":9.8,"dds":0.08163265306122447,"last_synced_commit":"f581b2fd322177e5fabd67af240811838c1c8fbc"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bramus%2Fansi-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bramus%2Fansi-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bramus%2Fansi-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bramus%2Fansi-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bramus","download_url":"https://codeload.github.com/bramus/ansi-php/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247276079,"owners_count":20912287,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansi","ansi-colors","ansi-escape-sequences","cli","php"],"created_at":"2024-08-01T11:01:04.741Z","updated_at":"2025-04-05T06:10:02.864Z","avatar_url":"https://github.com/bramus.png","language":"PHP","readme":"# ANSI PHP\n\n[![Build Status](https://img.shields.io/travis/bramus/ansi-php.svg?style=flat-square)](http://travis-ci.org/bramus/ansi-php) [![Source](http://img.shields.io/badge/source-bramus/ansi--php-blue.svg?style=flat-square)](https://github.com/bramus/ansi-php) [![Version](https://img.shields.io/packagist/v/bramus/ansi-php.svg?style=flat-square)](https://packagist.org/packages/bramus/ansi-php) [![Downloads](https://img.shields.io/packagist/dt/bramus/ansi-php.svg?style=flat-square)](https://packagist.org/packages/bramus/ansi-php/stats) [![License](https://img.shields.io/packagist/l/bramus/ansi-php.svg?style=flat-square)](https://github.com/bramus/ansi-php/blob/master/LICENSE)\n\nANSI Control Functions and ANSI Control Sequences for PHP CLI Apps\n\nBuilt by Bramus! - [https://www.bram.us/](https://www.bram.us/)\n\n## About\n\n`bramus/ansi-php` is a set of classes to working with ANSI Control Functions and ANSI Control Sequences on text based terminals.\n\n- ANSI Control Functions control an action such as line spacing, paging, or data flow.\n- ANSI Control Sequences allow one to clear the screen, move the cursor, set text colors, etc.\n\n_(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.)_\n\n## Features\n\nWhen it comes to ANSI Control Functions `bramus/ansi-php` supports:\n\n- `BS`: Backspace\n- `BEL`: Bell\n- `CR`: Carriage Return\n- `ESC`: Escape\n- `LF`: Line Feed\n- `TAB`: Tab\n\nWhen it comes to ANSI Escape Sequences `bramus/ansi-php` supports:\n\n- CUB _(Cursor Back)_: Move cursor back.\n- CUD _(Cursor Down)_: Move cursor down.\n- CUF _(Cursor Forward)_: Move cursor forward.\n- CUP _(Cursor Position)_: Move cursor to position.\n- CUU _(Cursor Up)_: Move cursor up.\n- ED _(Erase Display)_: Erase (parts of) the display.\n- EL _(Erase In Line)_: Erase (parts of) the current line.\n- SGR _(Select Graphic Rendition)_: Manipulate text styling (bold, underline, blink, colors, etc.).\n\nOther Control Sequences – such as DCH, NEL, etc. – are not (yet) supported.\n\nAn 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:\n\n![Monolog Colored Line Formatter](https://user-images.githubusercontent.com/11269635/28756233-c9f63abe-756a-11e7-883f-a084f35c55e7.gif)\n\n## Prerequisites/Requirements\n\n- PHP 5.4.0 or greater\n\n## Installation\n\nInstallation is possible using Composer\n\n```shell\ncomposer require bramus/ansi-php ~3.1\n```\n\n## Usage\n\nThe 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.\n\nIf you're feeling adventurous, you're of course free to use the raw `ControlFunction` and `ControlSequence` classes.\n\n### Quick example\n\n```php\nuse \\Bramus\\Ansi\\Ansi;\nuse \\Bramus\\Ansi\\Writers\\StreamWriter;\nuse \\Bramus\\Ansi\\ControlSequences\\EscapeSequences\\Enums\\SGR;\n\n// Create Ansi Instance\n$ansi = new Ansi(new StreamWriter('php://stdout'));\n\n// Output some styled text on screen, along with a Line Feed and a Bell\n$ansi-\u003ecolor(array(SGR::COLOR_FG_RED, SGR::COLOR_BG_WHITE))\n     -\u003eblink()\n     -\u003etext('I will be blinking red on a white background.')\n     -\u003enostyle()\n     -\u003etext(' And I will be normally styled.')\n     -\u003elf()\n     -\u003etext('Ooh, a bell is coming ...')\n     -\u003ebell();\n```\n\nSee more examples further down on how to use these.\n\n## Concepts\n\nSince 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.\n\nThe following writers are provided\n\n- `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`.\n- `BufferWriter`: Writes the data to a buffer. When calling `flush()` the contents of the buffer will be returned.\n- `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.\n\n## The `Ansi` helper class functions\n\n### Core functions:\n\n- `text($text)`: Write a piece of data to the writer\n- `setWriter(\\Bramus\\Ansi\\Writers\\WriterInterface $writer)`: Sets the writer\n- `getWriter()`: Gets the writer\n\n### ANSI Control Function shorthands:\n\nThese shorthands write a Control Character to the writer.\n\n- `bell()`:  Bell Control Character (`\\a`)\n- `backspace()`:  Backspace Control Character (`\\b`)\n- `tab()`:  Tab Control Character (`\\t`)\n- `lf()`:  Line Feed Control Character (`\\n`)\n- `cr()`:  Carriage Return Control Character (`\\r`)\n- `esc()`:  Escape Control Character\n\n### SGR ANSI Escape Sequence shorthands:\n\nThese shorthands write SGR ANSI Escape Sequences to the writer.\n\n- `nostyle()` or `reset()`: Remove all text styling (colors, bold, etc)\n- `color()`: Set the foreground and/or backgroundcolor of the text. _(see further)_\n- `bold()` or `bright()`: Bold: On. On some systems \"Intensity: Bright\"\n- `normal()`: Bold: Off. On some systems \"Intensity: Normal\"\n- `faint()`: Intensity: Faint. _(Not widely supported)_\n- `italic()`: Italic: On. _(Not widely supported)_\n- `underline()`: Underline: On.\n- `blink()`: Blink: On.\n- `negative()`: Inverse or Reverse. Swap foreground and background.\n- `strikethrough()`: Strikethrough: On. _(Not widely supported)_\n\n__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.\n\n### ED ANSI Escape Sequence shorthands:\n\nThese shorthands write ED ANSI Escape Sequences to the writer.\n\n- `eraseDisplay()`: Erase the entire screen and moves the cursor to home.\n- `eraseDisplayUp()`: Erase the screen from the current line up to the top of the screen.\n- `eraseDisplayDown()`: Erase the screen from the current line down to the bottom of the screen.\n\n### EL ANSI Escape Sequence shorthands:\n\nThese shorthands write EL ANSI Escape Sequences to the writer.\n\n- `eraseLine()`: Erase the entire current line.\n- `eraseLineToEOL()`: Erase from the current cursor position to the end of the current line.\n- `eraseLineToSOL()`: Erases from the current cursor position to the start of the current line.\n\n### CUB/CUD/CUF/CUP/CUU ANSI Escape Sequence shorthands:\n\n- `cursorBack($n)`: Move cursor back `$n` positions _(default: 1)_\n- `cursorForward($n)`: Move cursor forward `$n` positions _(default: 1)_\n- `cursorDown($n)`: Move cursor down `$n` positions _(default: 1)_\n- `cursorUp($n)`: Move cursor up `$n` positions _(default: 1)_\n- `cursorPosition($n, $m)`: Move cursor to position `$n,$m` _(default: 1,1)_\n\n### Extra functions\n\n- `flush()` or `get()`: Retrieve contents of a `FlushableWriter` writer.\n- `e()`: Echo the contents of a `FlushableWriter` writer.\n\n## Examples\n\n### The Basics\n\n```php\n// Create Ansi Instance\n$ansi = new \\Bramus\\Ansi\\Ansi();\n\n// This will output a Bell\n$ansi-\u003ebell();\n\n// This will output some text\n$ansi-\u003etext('Hello World!');\n```\n\n_NOTE:_ As no `$writer` is passed into the constructor of `\\Bramus\\Ansi\\Ansi`, the default `StreamWriter` writing to `php://stdout` is used.\n\n### Using a `FlushableWriter`\n\nFlushable Writers are writers that cache the data and only output it when flushed using its `flush()` function. The `BufferWriter` and `ProxyWriter` implement this interface.\n\n```php\n// Create Ansi Instance\n$ansi = new \\Bramus\\Ansi\\Ansi(new \\Bramus\\Ansi\\Writers\\BufferWriter());\n\n// This will append a bell to the buffer. It will not output it.\n$ansi-\u003ebell();\n\n// This will append a bell to the buffer. It will not output it.\n$ansi-\u003etext('Hello World!');\n\n// Now we'll output it\necho $ansi-\u003eget();\n```\n\n### Chaining\n\n`bramus/ansi-php`'s wrapper `Ansi` class supports chaining.\n\n```php\n// Create Ansi Instance\n$ansi = new \\Bramus\\Ansi\\Ansi();\n\n// This will output a Line Feed, some text, a Bell, and a Line Feed\n$ansi-\u003elf()-\u003etext('hello')-\u003ebell()-\u003elf();\n\n```\n\n### Styling Text: The Basics\n\n```php\n$ansi = new \\Bramus\\Ansi\\Ansi();\n$ansi-\u003ebold()-\u003eunderline()-\u003etext('I will be bold and underlined')-\u003elf();\n```\n\n__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.\n\n\n```php\n$ansi = new \\Bramus\\Ansi\\Ansi();\n\n$ansi-\u003ebold()-\u003eunderline()-\u003etext('I will be bold and underlined')-\u003elf();\n$ansi-\u003etext('I will also be bold because nostyle() has not been called yet')-\u003elf();\n$ansi-\u003enostyle()-\u003eblink()-\u003etext('I will be blinking')-\u003enostyle()-\u003elf();\n$ansi-\u003etext('I will be normal because nostyle() was called on the previous line');\n\n```\n\n### Styling Text: Colors\n\nColors, and other text styling options, are defined as contants on `\\Bramus\\Ansi\\ControlSequences\\EscapeSequences\\Enums\\SGR`.\n\n#### Foreground (Text) Colors\n\n- `SGR::COLOR_FG_BLACK`: Black Foreground Color\n- `SGR::COLOR_FG_RED`: Red Foreground Color\n- `SGR::COLOR_FG_GREEN`: Green Foreground Color\n- `SGR::COLOR_FG_YELLOW`: Yellow Foreground Color\n- `SGR::COLOR_FG_BLUE`: Blue Foreground Color\n- `SGR::COLOR_FG_PURPLE`: Purple Foreground Color\n- `SGR::COLOR_FG_CYAN`: Cyan Foreground Color\n- `SGR::COLOR_FG_WHITE`: White Foreground Color\n- `SGR::COLOR_FG_BLACK_BRIGHT`: Black Foreground Color (Bright)\n- `SGR::COLOR_FG_RED_BRIGHT`: Red Foreground Color (Bright)\n- `SGR::COLOR_FG_GREEN_BRIGHT`: Green Foreground Color (Bright)\n- `SGR::COLOR_FG_YELLOW_BRIGHT`: Yellow Foreground Color (Bright)\n- `SGR::COLOR_FG_BLUE_BRIGHT`: Blue Foreground Color (Bright)\n- `SGR::COLOR_FG_PURPLE_BRIGHT`: Purple Foreground Color (Bright)\n- `SGR::COLOR_FG_CYAN_BRIGHT`: Cyan Foreground Color (Bright)\n- `SGR::COLOR_FG_WHITE_BRIGHT`: White Foreground Color (Bright)\n- `SGR::COLOR_FG_RESET`: Default Foreground Color\n\n#### Background Colors\n\n- `SGR::COLOR_BG_BLACK`: Black Background Color\n- `SGR::COLOR_BG_RED`: Red Background Color\n- `SGR::COLOR_BG_GREEN`: Green Background Color\n- `SGR::COLOR_BG_YELLOW`: Yellow Background Color\n- `SGR::COLOR_BG_BLUE`: Blue Background Color\n- `SGR::COLOR_BG_PURPLE`: Purple Background Color\n- `SGR::COLOR_BG_CYAN`: Cyan Background Color\n- `SGR::COLOR_BG_WHITE`: White Background Color\n- `SGR::COLOR_BG_BLACK_BRIGHT`: Black Background Color (Bright)\n- `SGR::COLOR_BG_RED_BRIGHT`: Red Background Color (Bright)\n- `SGR::COLOR_BG_GREEN_BRIGHT`: Green Background Color (Bright)\n- `SGR::COLOR_BG_YELLOW_BRIGHT`: Yellow Background Color (Bright)\n- `SGR::COLOR_BG_BLUE_BRIGHT`: Blue Background Color (Bright)\n- `SGR::COLOR_BG_PURPLE_BRIGHT`: Purple Background Color (Bright)\n- `SGR::COLOR_BG_CYAN_BRIGHT`: Cyan Background Color (Bright)\n- `SGR::COLOR_BG_WHITE_BRIGHT`: White Background Color (Bright)\n- `SGR::COLOR_BG_RESET`: Default Background Color\n\nPass one of these into `$ansi-\u003ecolor()` and the color will be set.\n\n```php\nuse \\Bramus\\Ansi\\ControlSequences\\EscapeSequences\\Enums\\SGR;\n\n$ansi = new \\Bramus\\Ansi\\Ansi();\n\n$ansi-\u003ecolor(SGR::COLOR_FG_RED)\n     -\u003etext('I will be red')\n     -\u003enostyle();\n```\n\nTo set the foreground and background color in one call, pass them using an array to `$ansi-\u003ecolor()`\n\n```php\nuse \\Bramus\\Ansi\\ControlSequences\\EscapeSequences\\Enums\\SGR;\n\n$ansi = new \\Bramus\\Ansi\\Ansi();\n\n$ansi-\u003ecolor(array(SGR::COLOR_FG_RED, SGR::COLOR_BG_WHITE))\n     -\u003eblink()\n     -\u003etext('I will be blinking red on a wrhite background.')\n     -\u003enostyle();\n```\n\n### Creating a loading Spinner\n\nBy manipulating the cursor position one can create an in-place spinner\n\n```php\nuse \\Bramus\\Ansi\\Ansi;\nuse \\Bramus\\Ansi\\Writers\\StreamWriter;\nuse \\Bramus\\Ansi\\ControlSequences\\EscapeSequences\\Enums\\EL;\nuse \\Bramus\\Ansi\\ControlSequences\\EscapeSequences\\Enums\\SGR;\n\n// Create Ansi Instance\n$ansi = new Ansi(new StreamWriter('php://stdout'));\n\n// Parts of our spinner\n$spinnerParts = ['⣷','⣯','⣟','⡿','⢿','⣻','⣽','⣾'];\n\n$ansi-\u003etext('Loading Data')-\u003elf();\nfor ($i = 0; $i \u003c 100; $i++) {\n    $ansi\n        // Erase entire line\n        -\u003eel(EL::ALL)\n        // Go back to very first position on current line\n        -\u003ecursorBack(9999)\n        // Add a blue spinner\n        -\u003ecolor(SGR::COLOR_FG_BLUE)-\u003etext($spinnerParts[$i % sizeof($spinnerParts)])\n        // Write percentage\n        -\u003enostyle()-\u003etext(' ' . str_pad($i, 3, 0, STR_PAD_LEFT) . '%');\n\n    usleep(50000);\n}\n$ansi\n    -\u003eel(EL::ALL)\n    -\u003ecursorBack(9999)\n    -\u003ecolor(SGR::COLOR_FG_GREEN)-\u003etext('✔')\n    -\u003enostyle()-\u003etext(' 100%')\n    -\u003elf();\n```\n\nThis snippet will output a little loading spinner icon + the current percentage (e.g. `⣯ 009%`) that constantly updates in-place. When 100% is reached, the line will read `✔ 100%`.\n\n### Using the raw classes\n\nAs all raw `ControlFunction` and `ControlSequence` classes are provided with a `__toString()` function it's perfectly possible to directly `echo` some `bramus/ansi-php` instance.\n\n```php\n// Output a Bell Control Character\necho new \\Bramus\\Ansi\\ControlFunctions\\Bell();\n\n// Output an ED instruction, to erase the entire screen\necho new \\Bramus\\Ansi\\ControlSequences\\EscapeSequences\\ED(\n    \\Bramus\\Ansi\\ControlSequences\\EscapeSequences\\Enums\\ED::ALL\n);\n```\n\nTo fetch their contents, use the `get()` function:\n\n```php\n// Get ANSI string for a Bell Control Character\n$bell = (new \\Bramus\\Ansi\\ControlFunctions\\Bell())-\u003eget();\n\n// Get ANSI string for an ED instruction, to erase the entire screen\n$eraseDisplay = (new \\Bramus\\Ansi\\ControlSequences\\EscapeSequences\\ED(\n    \\Bramus\\Ansi\\ControlSequences\\EscapeSequences\\Enums\\ED::ALL\n))-\u003eget();\n\necho $bell . $bell . $eraseDisplay . $bell;\n```\n\n## Unit Testing\n\n`bramus/ansi-php` ships with unit tests using [PHPUnit](https://github.com/sebastianbergmann/phpunit/).\n\n- If PHPUnit is installed globally run `phpunit` to run the tests.\n\n- 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`\n\nUnit tests are also automatically run [on Travis CI](http://travis-ci.org/bramus/ansi-php)\n\n## License\n\n`bramus/ansi-php` is released under the MIT public license. See the enclosed `LICENSE` for details.\n\n## ANSI References\n\n- [http://en.wikipedia.org/wiki/ANSI_escape_code](http://en.wikipedia.org/wiki/ANSI_escape_code)\n- [http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-048.pdf](http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-048.pdf)\n- [http://wiki.bash-hackers.org/scripting/terminalcodes](http://wiki.bash-hackers.org/scripting/terminalcodes)\n- [http://web.mit.edu/gnu/doc/html/screen_10.html](http://web.mit.edu/gnu/doc/html/screen_10.html)\n- [http://www.isthe.com/chongo/tech/comp/ansi_escapes.html](http://www.isthe.com/chongo/tech/comp/ansi_escapes.html)\n- [http://www.termsys.demon.co.uk/vtansi.htm](http://www.termsys.demon.co.uk/vtansi.htm)\n- [http://rrbrandt.dee.ufcg.edu.br/en/docs/ansi/](http://rrbrandt.dee.ufcg.edu.br/en/docs/ansi/)\n- [http://tldp.org/HOWTO/Bash-Prompt-HOWTO/c327.html](http://tldp.org/HOWTO/Bash-Prompt-HOWTO/c327.html)\n","funding_links":[],"categories":["PHP"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbramus%2Fansi-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbramus%2Fansi-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbramus%2Fansi-php/lists"}