Telegram Entities Laravel Package

Product Decisions This Supports

• Build vs. buy (buy, clearly). Telegram text entities are expressed as (offset, length) pairs counted in UTF-16 code units, while PHP strings are UTF-8 bytes. Getting this right means handling surrogate pairs (emoji, flags, some CJK), grapheme clusters, and re-indexing after every edit. That is days of fiddly work plus a permanent tail of production bugs. Adopting a focused library here is a straightforward cost-avoidance decision.
• Feature scoping: rich message composition. If the roadmap includes formatted outbound messages — bold/italic/strikethrough/spoiler, inline code and pre blocks, text links, mentions, blockquotes — this package is the plumbing layer under that feature. It lets you accept author-friendly input (HTML or Markdown) and emit correct Telegram entities, and do the reverse for rendering Telegram content elsewhere.
• Roadmap enabler: user-authored and template-driven content. Admin panels, CMS-to-Telegram syndication, notification templates, and digest builders all need "author writes something → we send it formatted." This package turns that from a bespoke parser project into a dependency.
• Message editing and archiving. Any edit, truncation, or re-send requires recomputing entity offsets; any web archive or cross-posting feature requires converting entities back to HTML. Both are native to this library and painful to hand-roll.
• Input validation and sanitization. Inbound user content can carry malformed or malicious entity bounds. Validating and normalizing before persisting prevents downstream rendering failures and injection-style formatting abuse.
• Prioritization signal — treat as infrastructure, not a bet. With ~27 stars and a low opportunity score, this is not a differentiator and should never appear on a roadmap as a feature. It is a line item under "reduce delivery cost / reduce defect rate," and it competes against "we write it ourselves," not against other products.

When to Consider This Package

Adopt when:

• The stack is PHP 8.x with Composer, and you are integrating Telegram via the Bot API or MTProto.
• You accept user-supplied or template-supplied formatting and must convert it to entities (HTML/Markdown → entities) rather than just sending a fixed string.
• You need round-tripping: store content, re-send it, edit it, and render it in a web UI — all without offsets drifting.
• You already depend on MadelineProto; this library is by the same maintainer (danog) and is part of that ecosystem, so it is likely already in your dependency tree. Use it directly instead of re-implementing.
• You need entity-aware string operations (truncate a formatted message to N characters without splitting an entity or a surrogate pair).

Look elsewhere when:

• Outbound-only, static formatting. If you just need to send a bold line, the Bot API's parse_mode: HTML / MarkdownV2 is sufficient and adds zero dependencies. This library earns its place only when you must compute, inspect, or mutate offsets.
• You need a full bot framework. Nutgram, irazasyed/telegram-bot-sdk, or BotMan give you routing, conversations, and keyboards; treat entity handling as one narrow concern inside that choice rather than a reason to pick a stack.
• Heavy Markdown requirements. If authors need CommonMark extensions, tables, or a custom AST, pair league/commonmark with a thin entity converter, and verify this library's parser covers your accepted syntax subset before committing.
• Non-PHP services. No value outside the PHP runtime; the semantics (UTF-16 offsets) are portable, the code is not.
• Hard vendor-risk constraints. Single maintainer, small direct user base, no commercial support or SLA. Do not adopt it as a load-bearing component of a contractual deliverable without a fork-and-vendor plan.

Maturity read: Apache-2.0 (no legal friction), recent releases, and indirect adoption through MadelineProto's much larger install base are the reassuring signals. The 27-star count reflects how narrow the problem is, not poor quality — but it does mean you will be largely on your own for support.

How to Pitch It (Stakeholders)

To executives: A small, permissively licensed dependency that eliminates a known class of production defects — messages rejected by Telegram for invalid entity bounds, and mangled emoji or broken formatting in customer-facing notifications. Cost is near zero, integration is a day, and it removes recurring bug-fix churn from the team. It is not a strategic bet; approve it as a standard infrastructure dependency.

To engineering: This handles the UTF-16 code-unit offset math, surrogate-pair edge cases, and entity ↔ HTML/Markdown conversion so we stop hand-rolling mb_substr index juggling. It is maintained by the MadelineProto author, so it tracks Telegram's entity list, and it is already a transitive dependency in MadelineProto-based stacks. Vendor risk is bounded: the surface area is small, the license is Apache-2.0, and worst case we fork or vendor it in an afternoon.

The one caveat to state up front: if we only ever send fixed-format messages, we do not need this — the Bot API's parse_mode covers it. Approve it on the condition that the product supports user- or template-authored rich content, or needs to edit, truncate, archive, or cross-post formatted messages.