fisharebest / figlet
A zero-dependency PHP library and CLI for rendering FIGlet text banners.
Requires
- php: ^8.3
- composer-runtime-api: ^2.2
Requires (Dev)
- fisharebest/badge: ^1.0
- infection/infection: ^0.35
- phpstan/phpstan: ^2.3
- phpunit/phpunit: ^12.5
- squizlabs/php_codesniffer: ^4.0
- vimeo/psalm: ^7.11
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
A zero-dependency PHP library and CLI for rendering FIGlet text banners — useful for generating banner messages, project identities, and similar output for command-line tools.
__ _ _ _
/ _(_) __ _| | ___| |_
| |_| |/ _` | |/ _ \ __|
| _| | (_| | | __/ |_
|_| |_|\__, |_|\___|\__|
|___/
Installation
composer require fisharebest/figlet
Usage (library)
Render a message with a font loaded from a file:
use Fisharebest\Figlet\Font;
use Fisharebest\Figlet\Renderer;
use Fisharebest\Figlet\Options;
$font = Font::fromFile(__DIR__ . '/fonts/standard.flf');
$renderer = new Renderer();
echo $renderer->render('Hello', $font, new Options());
On the command line, a font is either a path to a .flf/.tlf file (with its
extension) or the name of one of the bundled fonts in fonts/ (without an
extension):
figlet -f slant Hello # bundled font by name
figlet -f /path/to/my/font.flf Hi # font file by path
Options
Options is immutable; every with*() method returns a new instance. Any
option left unset falls back to the font's own defaults.
use Fisharebest\Figlet\Direction;
use Fisharebest\Figlet\HorizontalMode;
use Fisharebest\Figlet\Justification;
use Fisharebest\Figlet\Options;
use Fisharebest\Figlet\VerticalMode;
$options = (new Options())
->withWidth(120) // wrap width (default 80)
->withJustification(Justification::Centre) // Left, Centre or Right
->withDirection(Direction::RightToLeft) // LeftToRight or RightToLeft
->withHorizontalMode(HorizontalMode::Kerning) // None, Kerning or Smushing
->withVerticalMode(VerticalMode::Smushing); // smush multi-line input vertically
echo (new FigletRenderer())->render("Hello\nWorld", $font, $options);
Colour output
Colour is applied after layout, so it never interferes with smushing. Build a
CellGrid from the rendered banner, choose a ColourScheme, and encode it with
an AnsiEncoder at the desired depth:
use Fisharebest\Figlet\CellGrid;
use Fisharebest\Figlet\Colour\AnsiEncoder;
use Fisharebest\Figlet\Colour\Colour;
use Fisharebest\Figlet\Colour\Depth;
use Fisharebest\Figlet\Colour\RainbowColourScheme;
use Fisharebest\Figlet\Colour\SolidColourScheme;
$banner = (new FigletRenderer())->render('Hello', $font, new Options());
$grid = CellGrid::fromText($banner);
$solid = new SolidColourScheme(Colour::fromString('#ff8800'));
$rainbow = new RainbowColourScheme();
$encoder = new AnsiEncoder(Depth::Bit24); // or Depth::Bit8 / Depth::Bit4 / Depth::None
echo $encoder->encode($grid, $rainbow);
Color::fromString() accepts colour names (red, bright-cyan, …),
#rrggbb/#rgb hex, and decimal ANSI palette indices. Depth::fromEnv()
inspects NO_COLOR, COLORTERM and TERM to pick a supported depth.
Usage (CLI)
figlet -f slant "Hello"
echo "Piped input" | figlet
figlet -f small --use-color=always --color-scheme=rainbow "Rainbow"
Options:
| Option | Description |
|---|---|
-f, --font=<font> | Font name or path to a .flf file (default: standard) |
-w, --width=<cols\|auto> | Output width for wrapping, or auto for the terminal width |
-j, --justify=<left\|centre\|center\|right> | Justification |
-d, --direction=<ltr\|rtl> | Left-to-right or right-to-left print direction |
-h, --horizontal-mode=<none\|kerning\|smushing> | Horizontal layout |
-v, --vertical-mode=<none\|smushing> | Vertical layout |
-c, --color=<colour> | Colour name, #rrggbb or ANSI index (implies solid colour) |
-u, --use-color=<never\|auto\|always> | When to emit ANSI colour (default: auto) |
-s, --color-scheme=<solid\|rainbow> | Colour scheme |
-?, --help | Show help |
The colour options also accept British spellings: --colour, --use-colour
and --colour-scheme.
Colour is emitted only to an interactive terminal under the default auto
mode; --use-color=always forces it (even when NO_COLOR is set) and
--use-color=never disables it. Run vendor/bin/figlet --help for the full list.
Fonts
A small set of classic fonts (standard, big, slant, small,
ansi-shadow and the TOIlet emboss and future) is bundled under
fonts/. Both FIGlet .flf and TOIlet .tlf fonts are supported and
can also be loaded by path. (TOIlet fonts often use Unicode box-drawing
sub-characters, so a UTF-8 terminal is required to display them.)
These fonts are not covered by this library's GPL licence. They are the
redistributed under their original terms — see fonts/CREDITS.md
for attribution and licensing.
More .flf and .tlf fonts are available online, for example:
To create your own font, see the FIGfont specification.
Credit
Thanks to Glen Chappell for creating the original figlet program. This project is based on his original C code.