{"id":37234609,"url":"https://github.com/php-tui/term","last_synced_at":"2026-01-15T03:59:54.803Z","repository":{"id":209440901,"uuid":"724071217","full_name":"php-tui/term","owner":"php-tui","description":"low-level terminal manipulation library for PHP","archived":false,"fork":false,"pushed_at":"2025-05-03T12:29:10.000Z","size":92,"stargazers_count":44,"open_issues_count":3,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-14T14:33:34.557Z","etag":null,"topics":[],"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/php-tui.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2023-11-27T10:39:25.000Z","updated_at":"2026-01-02T19:46:01.000Z","dependencies_parsed_at":"2023-12-01T15:41:42.020Z","dependency_job_id":null,"html_url":"https://github.com/php-tui/term","commit_stats":null,"previous_names":["php-tui/term"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/php-tui/term","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php-tui%2Fterm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php-tui%2Fterm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php-tui%2Fterm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php-tui%2Fterm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/php-tui","download_url":"https://codeload.github.com/php-tui/term/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php-tui%2Fterm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28442357,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T00:55:22.719Z","status":"online","status_checked_at":"2026-01-15T02:00:08.019Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2026-01-15T03:59:54.203Z","updated_at":"2026-01-15T03:59:54.799Z","avatar_url":"https://github.com/php-tui.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"PHP Term\n========\n\n[![CI](https://github.com/php-tui/term/actions/workflows/ci.yml/badge.svg)](https://github.com/php-tui/term/actions/workflows/ci.yml)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/php-tui/term/assets/530801/ca7a8e17-2238-496d-aaa8-83c92f2f5009\" alt=\"Term Logo\"/\u003e\n\u003c/p\u003e\n\nLow-level terminal control library **heavily** inspired by\n[crossterm](https://github.com/crossterm-rs/crossterm).\n\nTable of Contents\n-----------------\n\n- [Installation](#installation)\n- [Requiremens](#requirements)\n- [Usage](#usage)\n    - [Actions](#actions)\n    - [Events](#events)\n    - [Terminal Size](#terminal-size)\n    - [Raw Mode](#raw-mode)\n    - [ANSI parsing](#parsing)\n- [Testing](#testing)\n- [Contributing](#contributing)\n\nInstallation\n------------\n\n```\n$ composer require php-tui/term\n```\n\nRequirements\n------------\n\nI have only tested this library on Linux. It currently requires `stty` to\nenable the raw mode and detect the current window size. It should work on\nMacOS and WSL.\n\nNative **Windows** is currently not supported as I cannot test on Windows, the\narchitecture should support Windows however, so if you'd like to make a start\nlook at\n[crossterm](https://github.com/crossterm-rs/crossterm/blob/master/src/style/sys/windows.rs)\nfor inspiration and start a PR.\n\nUsage\n-----\n\n### Actions\n\nYou can send data to the terminal using _actions_.\n\n```php\n\u003c?php\n\n$terminal = Terminal::new();\n\n// queue an action\n$terminal-\u003equeue(Actions::printString('Hello World'));\n\n// flush the queue to the terminal\n$terminal-\u003eflush();\n\n// or you can execute it directly\n$terminal-\u003eexecute(Actions::printString('Hello World'));\n```\n\nAll actions are made available via. the `Actions` factory:\n\n| method | description |\n| --- | --- |\n| `Actions::requestCursorPosition` | Request the cursor position.\u003cbr/\u003e\u003cbr/\u003eThis will (hopefully) be returned by the terminal and will be provided\u003cbr/\u003eas an `PhpTui\\Term\\Event\\CursorPositionEvent`. |\n| `Actions::alternateScreenEnable` | Enable the alternate screen.\u003cbr/\u003e\u003cbr/\u003eAllows switching back to the users previous \"screen\" later. |\n| `Actions::alternateScreenDisable` | Disable the alternate screen |\n| `Actions::printString` | Echo a standard string to the terminal |\n| `Actions::cursorShow` | Show the cursor |\n| `Actions::cursorHide` | Hide the cursor |\n| `Actions::setRgbForegroundColor` | Set the foreground color using RGB |\n| `Actions::setRgbBackgroundColor` | Set the background color using RGB |\n| `Actions::setForegroundColor` | Set the foreground color to one of the ANSI base colors |\n| `Actions::setBackgroundColor` | Set the background color to one of the ANSI base colors |\n| `Actions::moveCursor` | Move the cursor to an absolute position.\u003cbr/\u003e\u003cbr/\u003eThe top left cell is 0,0. |\n| `Actions::reset` | Reset all modes (styles and colors) |\n| `Actions::bold` | Enable or disable the bold styling |\n| `Actions::dim` | Enable or disable the dim styling |\n| `Actions::italic` | Enable or disable the italic styling |\n| `Actions::underline` | Enable or disable the underline styling |\n| `Actions::slowBlink` | Enable or disable the slow blink styling |\n| `Actions::rapidBlink` | Enable or disable the rapid blink styling |\n| `Actions::reverse` | Enable or disable the reverse blink styling |\n| `Actions::hidden` | Enable or disable the hidden styling - useful for passwords. |\n| `Actions::strike` | Enable or disable the strike-through styling |\n| `Actions::clear` | Perform a clear operation.\u003cbr/\u003e\u003cbr/\u003eThe type of clear operation is given with the Enum for example\u003cbr/\u003e\u003cbr/\u003e`Actions::clear(ClearType::All)`\u003cbr/\u003e\u003cbr/\u003eWill clear the entire screen. |\n| `Actions::enableMouseCapture` | Enable mouse capture.\u003cbr/\u003e\u003cbr/\u003eOnce this action has been issued mouse events will be made available. |\n| `Actions::disableMouseCapture` | Disable mouse capture |\n| `Actions::scrollUp` | Scroll the terminal up the given number of rows |\n| `Actions::scrollDown` | Scroll the terminal down the given number of rows |\n| `Actions::setTitle` | Set the title of the terminal for the current process. |\n| `Actions::lineWrap` | Enable or disable line wrap |\n| `Actions::moveCursorNextLine` | Move the cursor down and to the start of the next line (or the given number of lines) |\n| `Actions::moveCursorPreviousLine` | Move the cursor up and to the start of the previous line (or the given number of lines) |\n| `Actions::moveCursorToColumn` | Move the cursor to the given column (0 based) |\n| `Actions::moveCursorToRow` | Move the cursor to the given row (0 based) |\n| `Actions::moveCursorUp` | Move cursor up 1 or the given number of rows. |\n| `Actions::moveCursorRight` | Move cursor right 1 or the given number of columns. |\n| `Actions::moveCursorDown` | Move cursor down 1 or the given number of rows. |\n| `Actions::moveCursorLeft` | Move cursor left 1 or the given number of columns. |\n| `Actions::saveCursorPosition` | Save the cursor position |\n| `Actions::restoreCursorPosition` | Restore the cursor position |\n| `Actions::enableCusorBlinking` | Enable cursor blinking |\n| `Actions::disableCursorBlinking` | Disable cursor blinking |\n| `Actions::setCursorStyle` | Set the cursor style |\n\n### Events\n\nTerm provides user events:\n\n```php\nwhile (true) {\n    while ($event = $terminal-\u003eevents()-\u003enext()) {\n        if ($event instanceof CodedKeyEvent) {\n            if ($event-\u003ecode === KeyCode::Esc) {\n                // escape pressed\n            }\n        }\n        if ($event instanceof CharKeyEvent) {\n            if ($event-\u003echar === 'c' \u0026\u0026 $event-\u003emodifiers === KeyModifiers::CONTROL) {\n                // ctrl-c pressed\n            }\n        }\n    }\n    usleep(10000);\n}\n```\n\nThe events are as follows:\n\n- `PhpTui\\Term\\Event\\CharKeyEvent`: Standard character key\n- `PhpTui\\Term\\Event\\CodedKeyEvent`: Special key, e.g. escape, control, page\n  up, arrow down, etc\n- `PhpTui\\Term\\Event\\CursorPositionEvent`: as a response to\n  `Actions::requestCursorPosition`.\n- `PhpTui\\Term\\Event\\FocusEvent`: for when focus has been gained or lost\n- `PhpTui\\Term\\Event\\FunctionKeyEvent`: when a function key is pressed\n- `PhpTui\\Term\\Event\\MouseEvent`: When the\n  `Actions::enableMouseCapture` has been called, provides mouse event\n  information.\n- `PhpTui\\Term\\Event\\TerminalResizedEvent`: The terminal was resized.\n\n### Terminal Size\n\nYou can request the terminal size:\n\n```php\n\u003c?php\n\n$terminal = Terminal::new();\n\n$size = $terminal-\u003einfo(Size::class);\nif (null !== $size) {\n    echo $size-\u003e__toString() . \"\\n\";\n} else {\n    echo 'Could not determine terminal size'.\"\\n\";\n}\n```\n\n### Raw Mode\n\nRaw mode disables all the default terminal behaviors and is what you typically\nwant to enable when you want a fully interactive terminal.\n\n```php\n\u003c?php\n\n$terminal = Terminal::new();\n$terminal-\u003eenableRawMode();\n$terminal-\u003edisableRawMode();\n```\n\nAlways be sure to disable raw mode as it will leave the terminal in a barely\nuseable state otherwise!\n\n### Parsing\n\nIn addition Term provides a parser which can parse any escape code emitted by\nthe actions.\n\nThis is useful if you want to capture the output from a terminal application\nand convert it to a set of Actions which can then be redrawn in another medium\n(e.g. plain text or HTML).\n\n```php\nuse PhpTui\\Term\\AnsiParser;\n$actions = AnsiParser::parseString($rawAnsiOutput, true);\n```\n\n## Testing\n\nThe `Terminal` has testable versions of all it's dependencies:\n\n```php\n\u003c?php\n\n$painter = ArrayPainter::new();\n$eventProvider = ArrayEventProvider::fromEvents(\n    CharKeyEvent::new('c')\n);\n$infoProvider = ClosureInformationProvider::new(\n    function (string $classFqn): TerminalInformation {\n        return new class implements TerminalInformation {};\n    }\n);\n$rawMode = new TestRawMode();\n\n$term = Terminal::new(\n    painter: $painter,\n    infoProvider: $infoProvider,\n    eventProvider: $eventProvider,\n    rawMode: $rawMode\n);\n$term-\u003eexecute(\n    Actions::printString('Hello World'),\n    Actions::setTitle('Terminal Title'),\n);\n\necho implode(\"\\n\", array_map(\n    fn (Action $action) =\u003e $action-\u003e__toString(),\n    $painter-\u003eactions()\n)). \"\\n\";\n```\n\nSee the example `testable.php` in `examples/`.\n\n## Contributing\n\nPRs for missing functionalities and improvements are charactr.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphp-tui%2Fterm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphp-tui%2Fterm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphp-tui%2Fterm/lists"}