PHP TUI brings Ratatui style console interfaces to PHP

A port of the Rust TUI ideas rather than a clone

php-tui is described in the README as a library for making awesome console applications in PHP, and it is explicitly a port of Rust's Ratatui. The tagline is Make awesome console applications in PHP, and the project description says it is a port of Ratatui.

The reason to care about that framing is that it tells you where the design comes from. Ratatui is a Rust library for building terminal user interfaces, and the PHP library takes from it the model of a widget tree that is rendered into a buffer, which is a different way of thinking from writing escape sequences by hand as you go.

The feature list is short and specific. Most widgets and shapes from Ratatui are supported. Advanced terminal control is heavily inspired by Rust's crossterm library, which is the low level crate Ratatui itself sits on. There is font and image rendering. And layout control uses the Cassowary algorithm through the separate php-tui/cassowary package. The README points at php-tui.github.io/php-tui for more.

The audience is PHP developers who want to write an interactive terminal application, a monitoring dashboard or a configuration tool, and who currently have two options: escape codes by hand, or shelling out to a framework written in another language. The project is MIT licensed, the primary language is PHP, the default branch is main, and the last push was on 2026-05-04.

Three separate problems: widgets, terminal control and layout

The feature list reads like three separate libraries, and that is the design.

The widget layer is the Ratatui inheritance. Most of the shapes and widgets from Ratatui are available, so the mental model of a layout with widgets placed into rectangles, then composed into a screen, transfers directly. The demo in the repository, and the animated recording linked in the README, show what that produces.

The terminal control layer is the crossterm inheritance. crossterm is what actually moves the cursor, changes colours, manages the alternate screen and reads key events, and it is the part where a terminal library either works or fights the terminal. Porting that behaviour to PHP is the unglamorous part of the work and the part that decides whether the library feels native or feels like a wrapper.

The layout layer is the one worth explaining. Layout control uses the Cassowary algorithm, a constraint solver for laying out user interfaces, and the implementation lives in its own package, php-tui/cassowary. That is a meaningful design choice. A terminal layout can be done with hardcoded offsets, which breaks the moment the window is resized, or with a simple flexbox style algorithm, which handles the common cases. A constraint solver lets you state that one pane takes the remaining space, another is a fixed width, and a third is half of what is left, and have the solver work out the numbers for the current terminal size.

The cost of a solver is that you now have a dependency, and that layout errors surface as unsatisfiable constraints rather than as an off by one. Both are acceptable prices, and the second is a better failure mode than the first.

Font and image rendering are the unusual inclusions

Font and image rendering is the item on the feature list that most distinguishes this from a general purpose terminal library, and it is worth asking what it means in practice.

Terminals have no font API in the general case, so a library that claims font rendering is either using escape sequences that shift a character cell into a different weight, or it is drawing the glyphs as pixels, or it is using a terminal with graphics support such as one that accepts inline images. Whatever the mechanism, it is the kind of feature that has to be done at the character cell level, because that is the only unit a terminal gives you.

Image rendering in a terminal has the same constraint, and it is the reason a library like this depends on careful terminal capability detection rather than assuming every terminal is the same.

Together, these two features point at the intended use. A terminal dashboard that shows a small logo, or a sparkline style glyph set, or a boxed chart, is different from a terminal application that prints a table. The demo in the repository is the way to see which of the two the author had in mind.

The trade is portability. The more a library leans on specific terminal capabilities, the more it inherits the differences between terminals, and the more it has to degrade. The README is honest about the current state of that, and about the one platform gap discussed below.

Installing it and running the demo

Installation is a Composer requirement, which is the only step the README documents:

composer require php-tui/php-tui

The documentation lives at php-tui.github.io/php-tui, and the README's Documentation section is a single line pointing there rather than any in repository tutorial. That is worth noting, because the widget set is large and the API surface for a TUI library is not something you can guess from a class name.

To see the library in action without writing anything, you check out the project and run the demo:

./example/demo/bin/demo

The repository has two example directories, example/demo/ and example/docs/, so the second one is presumably a version of the demo that corresponds to the documentation, which is a sensible arrangement for a project where the documentation is the main reference.

The rest of the top level is the usual modern PHP project furniture. There is a composer.json, a lib/ directory and a src/ directory, tests/ with a phpunit.xml, a phpstan.neon with a phpstan-baseline.neon for static analysis exceptions, a phpbench.json for benchmarks, a rector.php for automated refactoring, a .php-cs-fixer.dist.php for coding standards, a CHANGELOG.md, and a scripts/ directory. There is also a flake.nix and flake.lock, so a Nix development environment is available, and .gitattributes for line ending handling.

The toolchain is more ambitious than the version number

The published release history is 0.0.2 on 2023-11-21, 0.1.0 on 2023-11-29 and 0.2.1 on 2024-09-08, and the repository has no GitHub releases, so the version you get from Composer is the one to look at. The last push was on 2026-05-04, which is more recent than the last tag, so work has continued in the repository without a new release.

Against that, the tooling in the tree is considerable. Static analysis with PHPStan in strict enough form to need a baseline file, a Rector configuration for automated refactoring, PHP CS Fixer for style, PHPUnit for the test suite, and a phpbench.json for microbenchmarks. There is a CI workflow badge in the README pointing at a ci.yml workflow, and a CHANGELOG.md rather than release tags.

The interesting thing is the mismatch between a 0.x version and a toolchain of this quality. It suggests a project that has the engineering discipline of a mature library and the public API surface of an early one, which is the usual profile of a port that is being built out in public. For an adopter, that means the widget set and the API are likely to move, and the benchmark and static analysis infrastructure is what you can rely on to catch the breakage.

The one documented limitation is the one to plan around.

Windows is the gap, and the README is blunt about it

The Limitations section of the README has one entry. Windows support should not be hard to implement, but the author does not have Windows, and the sentence trails off with the ellipsis.

That single line covers several distinct problems. A terminal library depends on how the platform handles console mode, input encoding and the specific control sequences it emits, and Windows has historically been the awkward one, which is why the Rust libraries in this space spent years on Windows specific code paths. Without a maintainer who can run it, a Windows path in this library will be unverified, and a TUI that renders wrongly on the terminal your users actually have is worse than no TUI at all.

So the practical scope is Unix-like terminals, and any project that needs to ship to Windows users should either write a separate front end or wait for that support to appear. The README's own phrasing suggests it is intended rather than refused, which is a better position to be in than a hard no.

Everything else about the project is ordinary: MIT licence, a clean separation between the library and the examples, documentation published as a site, and a CI workflow that runs on every change. For a PHP developer who wants a structured terminal interface and is willing to work on a platform other than Windows, the pieces are in place, and the documentation site rather than the README is where the actual API reference lives.

Editorial conclusion

Adopt php-tui if you are writing a console application in PHP and want a structured widget model with constraint based layout rather than hand drawn ANSI escapes, and you are comfortable with a 0.x library. Do not adopt it if you need Windows support, since the README states that support should not be hard to implement but the author does not have Windows, or if your application must run in an environment without a modern terminal. Before you start, check the published version, which is 0.2.1, read the documentation site for the widget set that actually exists, and confirm the terminal you target supports the control sequences the renderer emits.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. php-tui/php-tui on GitHub
4. README
5. Releases