Download the PHP package wazum/stipple without Composer

stipple

Render small SVG icons as monochrome ANSI in the terminal — pure PHP, zero system dependencies.

Drop it into any PHP CLI tool that wants real icons next to its menu items. The output is a plain string ending in \n per row — works equally well with echo, Symfony Console, Laravel/Prompts, or whatever else writes to a TTY. Two pluggable samplers ship: Braille (default) for highest density and half-block as a more universal fallback.

Preview

The actions-brand-github icon from TYPO3.Icons (MIT-licensed) — source SVG and Braille rendering at heights 4, 6, 8:

Same icon at height(8) rendered with the half-block sampler — coarser, but works in any terminal/font:

Install

Requires PHP 8.2+ with ext-gd, ext-mbstring, ext-dom, ext-simplexml. No system binaries needed — rasterization is handled in pure PHP via meyfa/php-svg.

Usage

The output is a plain string ending in \n per row, safe to echo or pass to Laravel/Prompts' note()/info().

Samplers

For a 16×16 SVG at height(4) the Braille sampler maps 1:1 with the source pixel grid; at height(8) it super-samples 2×.

Alignment note. Blank Braille cells emit U+2800 so adjacent icons stay column-aligned in fonts that render U+2800 narrower than other Braille glyphs. The half-block sampler emits raw spaces for blank rows — usually fine, but two icons rendered side-by-side may drift by a column on terminals/fonts that treat space and █ as different widths.

Demo

Two scripts are bundled in this repository. They run only from a checkout — the bin/ and examples/ directories are excluded from the Composer dist tarball, so they're not shipped to library consumers.

Pluggable rasterizer

The default rasterizer wraps meyfa/php-svg. You can swap in a different backend later by implementing RasterizerInterface:

Security

The preprocessor hardens SVG input before rasterization:

• DOCTYPE / ENTITY declarations are rejected pre-parse (XXE attack surface).
• <script>, <foreignObject>, and all <image> elements are rejected after parse — embedded raster is out of scope, and allowing <image href="file://..."/> would let the rasterizer dependency file_get_contents() arbitrary local files.
• libxml is invoked with LIBXML_NONET (no network).
• currentColor is substituted with a configurable foreground hex; var(--icon-color-accent, ...) is resolved DOM-side so the rasterizer never has to deal with CSS custom properties.

Supported SVG features

The preprocessor handles common patterns found in icon SVGs from any source:

• fill="currentColor" and stroke="currentColor" — substituted with #ffffff so the rasterizer always renders at full luminance, regardless of the terminal foreground colour.
• style="fill: currentColor; …" — same substitution inside inline CSS, with other declarations preserved.
• var(--icon-color-accent, <fallback-hex>) — resolved DOM-side using either the configured accent() value or the embedded fallback hex (the rasterizer doesn't resolve CSS custom properties on its own).
• viewBox (space- or comma-separated) and root width/height numeric attributes for aspect-ratio resolution.

Anything not in the above list is passed through to the rasterizer untouched.

Development

License

MIT — see LICENSE. Bundled demo icons (examples/icons/) are MIT-licensed by the TYPO3.Icons project — see THIRD_PARTY_NOTICES.md.