README

Minecraft Text

A pure-PHP library for parsing and rendering Minecraft chat text in every format the live ecosystem uses: JSON text components, SNBT text components, legacy §/&-coded strings, MiniMessage, and HTML.

Features

Five input formats: JSON text components, SNBT text components, legacy §/&-coded strings (with the BungeeCord and Essentials hex extensions), and MiniMessage; readers are permissive by default with an opt-in strict mode
Five output formats: JSON, SNBT, legacy, MiniMessage, and HTML; the HTML renderer is configurable for inline styles, CSS classes, or a hybrid, with a bundled reference stylesheet
Dialect-targeted rendering: pick the Minecraft schema generation (1.20, 1.20.5, 1.21.4, 1.21.5, 26.1) and the JSON/SNBT renderers emit the canonical wire shape — correct event-key casing, allowed click and hover actions, shadow_color support, and show_item payload form
Round-trip integrity: unknown click actions survive as CustomClickEvent; MiniMessage gradient/rainbow/transition tags round-trip verbatim through the MiniMessage renderer (other renderers lower them to plain text spans)
Diagnostics, not exceptions: lossy and non-canonical inputs record a Diagnostic against the parse or render result rather than throwing, with stable dotted codes (parse.minimessage.unknown-tag, render.legacy.translate-dropped, render.html.url-scheme-blocked, ...) suitable for programmatic filtering
Six native component types (Text, Translate, Keybind, Score, Selector, NBT) plus three MiniMessage-native transformations (Gradient, Rainbow, Transition)
Style inheritance matching vanilla Minecraft semantics, with a tri-state Decorations record so children can suppress an inherited decoration (<!bold>)
Fluent builder (TextBuilder) and a static facade (Text) for programmatic construction without manual AST assembly
Translation resolution via a caller-supplied locale source, with a printf-style placeholder helper (%s / %1$s / %%)
HTML safety: every text leaf is HTML-escaped, URL schemes in OpenUrl are validated against a configurable allowlist (default http/https/mailto), and obfuscated text is exposed via a data-mc-text attribute for client-side animation
PHPStan level max with full generic annotations; 100% mutation score under Infection (all surviving mutants documented as observationally equivalent)

Requirements

PHP 8.5 or newer
cartograph/minecraft-nbt ^1.0 (resolved automatically by Composer)

No PHP extensions are required.

Installation

Install via Composer:

composer require cartograph/minecraft-text

Quick start

Parse a legacy MOTD and render it as themed HTML:

use Cartograph\Text\Text;

$html = Text::renderHtml(Text::parseLegacy("§6Welcome §eto §athe server"));
// <span class="mc-color-gold">Welcome </span>
// <span class="mc-color-yellow">to </span>
// <span class="mc-color-green">the server</span>

That's a complete, runnable example. The bundled reference stylesheet (Html::referenceStylesheet()) defines the default mc-color-* and mc-bold rules so the output drops straight into any page.

Build a tree programmatically and serialise it as JSON for Minecraft:

use Cartograph\Text\Component\NamedColor;
use Cartograph\Text\Text;

$component = Text::text(
    'Hello, ',
    children: [
        Text::text('world', style: Text::build()->color(NamedColor::Red)->build()->style()),
        Text::text('!'),
    ],
);

echo Text::renderJson($component);
// {"text":"Hello, ","extra":[{"text":"world","color":"red"},{"text":"!"}]}

Concepts

Minecraft chat text is a tree of typed components. Each component carries some content (literal text, a translation key, a keybind, a score reference, a selector, or an NBT path) plus an optional style (colour, decorations, font, shadow colour, click/hover events, insertion text) and an "extra" list of child components that inherit the parent's effective style.

Vanilla Minecraft serialises this tree in three main ways:

JSON text components, the wire format used by chat, signs, written books, advancement descriptions, and the SLP status response
SNBT text components, the same shape encoded as stringified NBT for use in commands and data packs
Legacy §-codes, the pre-1.7 wire format still emitted by plugins, written into pre-1.13 worlds, and used by SLP MOTDs

The community uses two more:

MiniMessage, a tag-language popularised by the Adventure library (Paper, Velocity), with native syntax for gradients, rainbows, and click/hover events
HTML, for displaying chat on websites

This library reads, writes, and converts between all five. A shared, immutable Component AST sits between the readers and the renderers, so any input format can be re-rendered to any output format.

Output that targets Minecraft's JSON/SNBT wire format is dialect- driven: a Profile for the target Minecraft generation decides which fields are valid, which click/hover actions are allowed, what casing event keys use (clickEvent vs click_event), and whether shadow_color and the legacy NBT-string show_item payload are supported. Fields the dialect cannot represent record a Diagnostic and drop, or throw ProfileMismatchException under strict mode.

Lossy conversions (rendering a KeybindComponent to legacy, an unresolved TranslateComponent to HTML, an unknown <wibble> tag in MiniMessage) record dotted diagnostics on the result rather than silently failing.

Usage

Parse JSON, SNBT, legacy, or MiniMessage

Every reader has two facade entry points: a one-shot version returning just the parsed Component, and a *Result version returning a ParseResult bundling the component with any diagnostics raised.

use Cartograph\Text\Text;

$c1 = Text::parseJson('{"text":"hi","color":"red"}');
$c2 = Text::parseSnbt('{text:"hi",color:"red"}');
$c3 = Text::parseLegacy('§chi');
$c4 = Text::parseMiniMessage('<red>hi</red>');

// Or with diagnostics:
$r = Text::parseJsonResult($input);
$component   = $r->component;
$diagnostics = $r->diagnostics; // list<Diagnostic>

Parsers are permissive by default — bare strings, list-as-component, both clickEvent and click_event casings, both legacy and modern show_item payloads, and unknown click actions all parse without throwing. Pass new JsonOptions(strict: true) (or the per-format equivalent) to reject non-canonical shapes.

Render to JSON, SNBT, legacy, MiniMessage, or HTML

use Cartograph\Text\Text;

echo Text::renderJson($c);
echo Text::renderSnbt($c);
echo Text::renderLegacy($c);
echo Text::renderMiniMessage($c);
echo Text::renderHtml($c);

// `*Result` variants return diagnostics alongside the text:
$r = Text::renderHtmlResult($c);
$html        = $r->text;
$diagnostics = $r->diagnostics;

The JSON and SNBT renderers take a JsonOptions / SnbtOptions with a dialect field — pick the Minecraft schema generation you're targeting:

use Cartograph\Text\Json\JsonOptions;
use Cartograph\Text\Profile\JsonDialect;
use Cartograph\Text\Text;

echo Text::renderJson($c, new JsonOptions(JsonDialect::Mc1_20));
// Pre-1.21.5 wire shape: clickEvent (camelCase), legacy show_item, no shadow_color

echo Text::renderJson($c, new JsonOptions(JsonDialect::Mc26_1));
// Latest wire shape: click_event (snake_case), components-form show_item, shadow_color

Build trees programmatically

Two equivalent APIs:

The Text facade has a static factory for every component type:

use Cartograph\Text\Component\NamedColor;
use Cartograph\Text\Component\Style;
use Cartograph\Text\Component\Decorations;
use Cartograph\Text\Text;

$c = Text::text(
    'Hello',
    style: new Style(color: NamedColor::Gold, decorations: new Decorations(bold: true)),
);

TextBuilder is a fluent, immutable helper for chained construction:

use Cartograph\Text\Build\TextBuilder;
use Cartograph\Text\Component\NamedColor;
use Cartograph\Text\Component\Events\OpenUrl;
use Cartograph\Text\Text;

$c = Text::build()
    ->append(TextBuilder::text('Click here')
        ->color(NamedColor::Aqua)
        ->underlined()
        ->onClick(new OpenUrl('https://example.com')))
    ->append(TextBuilder::text(' to continue.'))
    ->build();

Resolve translations

TranslationResolver walks a tree replacing every TranslateComponent with its resolved text. The package ships no locale data — implement the Translator interface against your own locale source:

use Cartograph\Text\Translation\TranslationResolver;
use Cartograph\Text\Translation\Translator;

$translator = new class implements Translator {
    public function translate(string $key, ?string $locale = null): ?string
    {
        return match ($key) {
            'chat.type.text' => '<%s> %s',
            default          => null,
        };
    }
};

$resolved = new TranslationResolver($translator)->resolve($component);

The HtmlRenderer accepts an optional Translator via HtmlOptions and runs the resolution pass automatically before walking the tree.

Customise HTML rendering

use Cartograph\Text\Html\EventStrategy;
use Cartograph\Text\Html\HtmlOptions;
use Cartograph\Text\Html\StaticPalette;
use Cartograph\Text\Html\StylingMode;
use Cartograph\Text\Text;

$opts = new HtmlOptions(
    stylingMode:       StylingMode::Inline,        // Inline / Classes / Hybrid (default)
    classPrefix:       'mc-',
    events:            EventStrategy::AnchorPlusData,
    palette:           StaticPalette::sign(),      // chat (default) or sign
    allowedUrlSchemes: ['https'],                  // default ['http','https','mailto']
);

echo Text::renderHtml($component, $opts);

The bundled reference stylesheet (Html::referenceStylesheet()) defines the default mc-color-*, mc-bold, mc-italic, etc. classes plus a CSS-only animation for mc-obfuscated.

Class overview

The public surface splits into the AST (Component namespace), the five readers, the five renderers, the dialect/profile system, and a small set of supporting types.

Entry point

Class	Method group	Returns
`Text`	`parseJson`/`parseSnbt`/`parseLegacy`/`parseMiniMessage` (+`*Result`)	`Component` (or `ParseResult`)
`Text`	`renderJson`/`renderSnbt`/`renderLegacy`/`renderMiniMessage`/`renderHtml` (+`*Result`)	`string` (or `RenderResult`)
`Text`	`text`/`translate`/`keybind`/`score`/`selector`/`nbt`/`gradient`/`rainbow`/`transition`	the matching `*Component`
`Text`	`color(string\|int\|NamedColor)`	`Color`
`Text`	`build()`	`TextBuilder` seeded with empty text

Component AST (`Cartograph\Text\Component`)

Class	Role
`Component`	sealed interface implemented by every node
`TextComponent`	literal text (JSON `{"text": "..."}`)
`TranslateComponent`	locale key + `with` arguments (JSON `{"translate": ...}`)
`KeybindComponent`	keybind reference, e.g. `key.jump`
`ScoreComponent`	scoreboard score reference
`SelectorComponent`	target selector, e.g. `@p`, with optional separator
`NbtComponent`	NBT path read from a block/entity/storage
`GradientComponent`	MiniMessage-native colour gradient
`RainbowComponent`	MiniMessage-native HSL hue cycle
`TransitionComponent`	MiniMessage-native single sampled colour
`Style`	immutable container for colour, decorations, font, events, etc.
`Decorations`	tri-state record of bold/italic/underlined/strikethrough/obfuscated
`Color` / `NamedColor` / `HexColor`	colour interface and its two implementations
`NbtSource`	enum: `Block`, `Entity`, `Storage`
`Events\ClickEvent`	sealed: `OpenUrl`, `RunCommand`, `SuggestCommand`, `CopyToClipboard`, `ChangePage`, `CustomClickEvent`
`Events\HoverEvent`	sealed: `ShowText`, `ShowItem`, `ShowEntity`

Readers and renderers

Format	Reader	Renderer	Options class
JSON	`JsonReader`	`JsonRenderer`	`JsonOptions`
SNBT	`SnbtReader`	`SnbtRenderer`	`SnbtOptions`
Legacy	`LegacyReader`	`LegacyRenderer`	`LegacyOptions`
MiniMessage	`MiniMessageReader`	`MiniMessageRenderer`	`MiniMessageOptions`
HTML	—	`HtmlRenderer`	`HtmlOptions`

Profiles and diagnostics

Class	Role
`Profile\JsonDialect`	enum: `Mc1_20`, `Mc1_20_5`, `Mc1_21_4`, `Mc1_21_5`, `Mc26_1`
`Profile\Profile`	per-dialect field naming and action allowlists
`Render\Diagnostic`	severity + dotted code + message + optional path/offset
`Render\Severity`	enum: `Info`, `Warning`, `Error`
`Read\ParseResult`	parsed component + diagnostics
`Render\RenderResult`	rendered text + diagnostics

Extension points

Class / interface	Purpose
`MiniMessage\TagHandler`	Register custom MiniMessage tags via `TagRegistry::register`
`Html\Palette` / `Html\StaticPalette`	Map `NamedColor` to RGB; ship `chat()` and `sign()` palettes
`Translation\Translator`	Caller-supplied locale lookup

Compatibility

Minecraft Java versions: parsers accept every JSON/SNBT shape emitted between 1.20 and 26.1 (Minecraft Java's current major). Renderers target the same range via JsonDialect; pick the dialect matching the server/client you're talking to.
Legacy codes: classic § plus &, with BungeeCord §x§R§R§G§G§B§B hex (opt-in default-on) and Essentials &#RRGGBB hex (opt-in)
MiniMessage: the vanilla tag vocabulary — colours and aliases, decorations with <!negation> form, click/hover/insertion/font, content tags (<lang>, <key>, <score>, <selector>, <nbt>), transformations (<gradient>, <rainbow>, <transition>), plus <reset/> and <newline/>. Custom tags pluggable via TagHandler.
HTML: emits semantic markup with configurable styling mode, scheme-allowlisted click handlers, and a data-mc-* attribute convention for consumer-side JavaScript

Bedrock Edition's text format variants are not supported.

Contributing

Bug reports, feature requests, and pull requests are welcome at github.com/cartographgg/minecraft-text. See CONTRIBUTING.md for development setup and the required checks (tests, static analysis, code style, and mutation testing). Each check has a Composer script: composer test, composer static, composer style, and composer mutation.

License

Maintained as part of Cartograph, a Minecraft server directory and monitoring platform. The library is self-contained and has no Cartograph-specific behaviour; use it anywhere you need to work with Minecraft chat text in PHP.

cartograph / minecraft-text

Maintainers

Package info

Statistics

Security

README

Minecraft Text

Features

Requirements

Installation

Quick start

Concepts

Usage

Parse JSON, SNBT, legacy, or MiniMessage

Render to JSON, SNBT, legacy, MiniMessage, or HTML

Build trees programmatically

Resolve translations

Customise HTML rendering

Class overview

Entry point

Component AST (`Cartograph\Text\Component`)

Readers and renderers

Profiles and diagnostics

Extension points

Compatibility

Contributing

License

cartograph / minecraft-text

Maintainers

Package info

Statistics

Security

README

Minecraft Text

Features

Requirements

Installation

Quick start

Concepts

Usage

Parse JSON, SNBT, legacy, or MiniMessage

Render to JSON, SNBT, legacy, MiniMessage, or HTML

Build trees programmatically

Resolve translations

Customise HTML rendering

Class overview

Entry point

Component AST (Cartograph\Text\Component)

Readers and renderers

Profiles and diagnostics

Extension points

Compatibility

Contributing

License

Component AST (`Cartograph\Text\Component`)