README

Render Carve documents to chat-platform markup.

WhatsApp, Slack, Telegram and Discord each accept a small, mutually incompatible subset of Markdown-like markup, with different link syntax, different escaping rules and different length caps. This package renders a Carve document into any of them, and tells you what could not survive the trip.

Every platform is a JSON file, not a class. Adding one costs no PHP.

Install

composer require markup-carve/carve-php-chat

Usage

use MarkupCarve\Carve\CarveConverter;
use MarkupCarve\Chat\ChatRenderer;
use MarkupCarve\Chat\FlavorRegistry;

$document = CarveConverter::create()->parse($carveSource);
$flavor = (new FlavorRegistry())->get('slack');

echo (new ChatRenderer($flavor))->render($document);

ChatRenderer implements the core RendererInterface, so it also drops straight into CarveConverter:

$converter = CarveConverter::create(renderer: new ChatRenderer($flavor));
echo $converter->convert($carveSource);

Knowing what was lost

Chat formats cannot express most of Carve. renderResult() returns the text plus a record of every degradation, so a UI can warn rather than silently mangle:

$result = (new ChatRenderer($flavor))->renderResult($document);

echo $result->text;

foreach ($result->losses as $loss) {
    printf("line %s: %s\n", $loss->sourceLine ?? '?', $loss->reason);
}

Bundled flavors

id	notes
`whatsapp`	`bold`, `_italic_`, `~strike~`. No link markup at all, so links degrade to `text (url)`.
`slack`	mrkdwn. Links are `<url\|text>`. No heading syntax and no list syntax.
`telegram-html`	HTML parse mode: `<b> <i> <u> <s> <code> <pre> <a> <blockquote> <tg-spoiler>`.
`discord`	Headings and lists are native. Masked links are not, in user-typed messages.
`discord-bot`	`extends: discord`, with masked links enabled.
`signal`	Range-based: plain text plus style offsets. See below.
`telegram-entities`	Range-based variant of Telegram, for the Bot API `entities` field.

Why Discord has two flavors

[text](url) does not render in a message a human types into Discord. It renders in bot API messages, webhook content, embeds, and DMs from a bot. Discord made that trade-off deliberately, to stop malicious URLs hiding behind innocent text.

So pick discord when the output is pasted by a person, and discord-bot when your bot posts it. The two files differ by one key.

Two families of target

Chat platforms carry formatting in one of two ways, and a flavor declares which with output:

markup (the default) - formatting lives in the message string as delimiters. WhatsApp, Slack, Telegram parse_mode, Discord.
ranges - the body is plain text and the formatting travels beside it as offsets. Signal, Telegram's entities field, Slack Block Kit.

Signal is the clearest case: its documentation states that Markdown "is not supported at this time and is not planned". Formatting is applied by selecting text in the UI, so a typed *bold* stays literally *bold* - but the message still displays as bold, because the style rides along separately.

A range-based flavor names a style per node instead of delimiters:

"strong": { "support": "native", "style": "BOLD" }

A node the target cannot represent natively may still declare a style, so it degrades and carries the styling. Signal has no heading syntax, but a heading should not flatten to unremarkable text:

"heading": { "support": "none", "fallback": "inline", "template": "{content}", "style": "BOLD" }

ChatResult then carries the spans:

$result = (new ChatRenderer($registry->get('signal')))->renderResult($document);

$result->text;             // "Shipped bold and em." - no delimiters
$result->rangesToArray();  // [['start' => 8, 'length' => 4, 'style' => 'BOLD'], ...]

Offsets are counted in a declared unit

offsets is utf16 (default), utf8 or codepoints. This is not a detail to guess at - Telegram documents its entity offsets in UTF-16 code units, so a character outside the BMP counts as two:

unit	`start` of the bold span in `👍 bold`
`utf16`	3
`utf8`	5
`codepoints`	2

Measuring in the wrong unit shifts every range after the first such character.

Styles that carry more than a name

Once the delimiters are gone, the body has no room for a URL or a language, so the range carries them:

$result->rangesToArray();
// [
//   ['start' => 0,  'length' => 4, 'style' => 'text_link', 'url' => 'https://e.com/a'],
//   ['start' => 6,  'length' => 6, 'style' => 'blockquote'],
//   ['start' => 14, 'length' => 7, 'style' => 'pre', 'language' => 'php'],
// ]

Ranges are not limited to inline marks: blockquote and pre cover whole blocks, so a range-based body needs no > prefix and no fence.

Style names are the target's own, so rangesToArray() is close to what its API wants. Telegram calls the fields type, offset and length, so a caller renames three keys rather than deriving anything.

Custom flavors

A flavor is data. To add Matrix, Zulip, Google Chat or an internal tool, write a JSON file - no PHP:

{
  "id": "zulip",
  "label": "Zulip",
  "verified": "2026-07-21",
  "limits": { "message": 10000 },
  "link": { "style": "markdown" },
  "escape": { "mechanism": "backslash", "chars": "*_`" },
  "nodes": {
    "paragraph": { "support": "native" },
    "text":      { "support": "native" },
    "strong":    { "support": "native", "open": "**", "close": "**" },
    "emphasis":  { "support": "native", "open": "*",  "close": "*" },
    "code":      { "support": "native", "open": "`",  "close": "`" },
    "link":      { "support": "native" }
  }
}

$flavor = (new FlavorRegistry())->fromJsonFile('/path/to/zulip.json');

Node types not listed are treated as unsupported and degrade via their fallback.

Extensions

An extension is addressed by a qualified key, so a flavor maps that one extension rather than claiming every extension at once. Carve's spoiler is an extension, and several targets have a real spoiler of their own:

"inline_extension:spoiler": { "support": "native", "open": "||", "close": "||" }

A div that names itself keeps that name as a leading label, because chat has no box to draw around it: ::: warning becomes a Warning: line, and a titled ::: details "More info" becomes More info:. Without it a warning arrives as unlabelled prose.

Note that highlight ({=mark=}) is not a spoiler. Highlight emphasizes, a spoiler conceals; mapping one onto the other inverts what the author meant. No target has a highlight, so it keeps its Carve markup.

Deriving from an existing flavor

extends merges a parent, with the child's keys winning, so a tweak is a few lines rather than a full restatement. A node entry you declare replaces the inherited one outright, so state it fully - otherwise a key you did not restate (a parent's template, say) would stay in charge:

{
  "id": "slack-internal",
  "label": "Slack (internal)",
  "extends": "slack",
  "nodes": {
    "heading": { "support": "none", "fallback": "inline", "template": "*{content}*" }
  }
}

Schema

Keyed by MarkupCarve\Carve\NodeType constants.

field	values
`support`	`native`, `none`
`fallback`	`unwrap`, `carve`, `inline`, `codeblock`, `appendix`, `drop`
`link.style`	`none`, `markdown`, `slackPipe`, `html`
`escape.mechanism`	`backslash`, `entities`, `none`
`output`	`markup` (default), `ranges`
`offsets`	`utf16` (default), `utf8`, `codepoints` - range-based only
`style`	style name per node, range-based only (e.g. `BOLD`)

Template placeholders: {content}, {url}, {alt}, {title}, {hashes}.

Fallback meanings:

unwrap - emit the children, drop the markup
carve - keep Carve's own delimiters, so an inexpressible mark stays visible ({=highlighted=}, {^sup^}) instead of flattening into ordinary text
inline - emit via template, e.g. {alt} ({url})
codeblock - flatten to a column-aligned monospace block (tables)
appendix - collect and emit at the end, numbered (footnotes)
drop - omit entirely

Each flavor carries a verified date, and individual nodes may carry since, because platform syntax changes. Discord added headings and lists in 2023; Telegram added expandable blockquote in Bot API 7.3.

Message length

Flavors declare limits.message. Exceeding it records a loss; the text is returned whole and is not split. Splitting formatted text correctly (never inside a fence, never orphaning a **) is a separate problem.

License

MIT

markup-carve / carve-php-chat

Maintainers

Package info

Statistics

Security