# AGENTS.md — telegram-format-text ## Purpose This package converts HTML to Telegram Bot API-compatible text in four output formats: `text`, `HTML`, `Markdown`, and `MarkdownV2`. It is used by WordPress plugins to format post content and notifications for Telegram delivery. **Package**: `wpsocio/telegram-format-text` **Namespace**: `WPSocio\TelegramFormatText` **PHP**: 8.0+ ## Architecture ``` HtmlConverter (entry point) └─ Environment (converter registry) ├─ Configuration (options store) └─ Converters (one per HTML tag) └─ BaseConverter (abstract, routes to format-specific methods) ``` **Design pattern**: Strategy pattern — each HTML tag has a dedicated converter class. The `Environment` maps tag names to converter instances. `HtmlConverter` walks the DOM tree bottom-up, delegating each node to the appropriate converter. ## Key Files | File | Role | |------|------| | `src/HtmlConverter.php` | Public API. `convert($html)` and `safeTrim($html, $limitBy, $limit)` are the main entry points. | | `src/Environment.php` | Registry of converters. `createDefaultEnvironment()` wires up all built-in converters. | | `src/Configuration.php` | Stores options like `format_to`, `list_item_style`, `text_hyperlinks`, etc. | | `src/Element.php` | Wraps `DOMNode` with helper methods for traversal, type checks, and attribute access. | | `src/ElementInterface.php` | Interface contract for `Element`. | | `src/Converter/BaseConverter.php` | Abstract base class. Routes conversion to `convertToText()`, `convertToMarkdown()`, or `convertToHtml()` based on the configured format. Contains Markdown escape character maps. | | `src/Converter/Utils.php` | Static utilities: placeholder management, HTML entity decoding, text truncation, style parsing. | ## Converters (`src/Converter/`) Each converter extends `BaseConverter` and handles specific HTML tags: | Converter | Tags | Notes | |-----------|------|-------| | `TextConverter` | `#text` | Decodes entities, escapes Markdown special chars | | `EmphasisConverter` | `em`, `i`, `strong`, `b` | Prevents invalid nesting of same-type emphasis | | `LinkConverter` | `a` | Handles relative URLs, format-specific link syntax | | `ImageConverter` | `img` | Configurable alt/title behavior via `images_in_links` option | | `CodeConverter` | `code` | Inline and block code with language detection | | `PreformattedConverter` | `pre` | Preformatted text blocks | | `ListBlockConverter` | `ol`, `ul` | List containers | | `ListItemConverter` | `li` | Nested list support with configurable bullet styles | | `BlockquoteConverter` | `blockquote` | Only formatted in MarkdownV2 | | `TableConverter` | `table`, `tr`, `th`, `td`, `thead`, `tbody`, `tfoot`, `colgroup`, `col`, `caption` | Custom cell/row separators | | `HorizontalRuleConverter` | `hr` | Horizontal rules | | `SpoilerConverter` | `tg-spoiler`, `span` | Telegram spoilers (MarkdownV2 only) | | `CommentConverter` | `#comment` | Strips HTML comments | | `DefaultConverter` | fallback | Passes through children's text for unhandled tags | ## Conversion Flow 1. **Prepare HTML** (`prepareHtml`): Normalize whitespace, strip `/