Telegram Entities Laravel Package

Technical Evaluation

What the package is. A narrow, single-purpose PHP utility for Telegram's styled-text model. The Bot API returns message.text plus a entities[] array whose offset/length are measured in UTF-16 code units, while PHP strings are UTF-8 bytes and mbstring counts code points. danog/telegram-entities converts between those representations and (per its description) parses/serializes HTML-style markup to and from entity lists. It is plumbing, not a framework.

Architecture fit. Good, with one condition. There is no Laravel coupling here — no service provider, facade, config file, migrations, or published assets — so it slots in as a pure Composer library. The condition is that it must sit behind an anti-corruption layer: our domain code should traffic in our own FormattedMessage / EntitySpan value objects, with the library confined to an adapter in app/Support/Telegram/. Leaking a third-party entity type into notification classes or job payloads would make the eventual fork or replacement expensive for no reason.

Integration feasibility. High and cheap. The integration is a few dozen lines in a service class plus tests. A spike is a half-day; production integration is one sprint-shaped slice alongside the feature that needs it. There is no infrastructure prerequisite.

Technical risk. Runtime risk is low: pure computation, no I/O, no state, deterministic input/output, easy to test exhaustively. The risk is governance, not code:

• 27 stars and an unverified/unresolvable repository link means effectively zero community validation. We would be adopting on the strength of one maintainer's reputation (the author is credible in the Telegram/PHP space) rather than on adoption evidence.
• Bus factor of one. The opportunity score of 1.78 corroborates that this is a niche utility with a thin ecosystem around it.
• The release date metadata (2026-10-18) is anomalous relative to a package we are evaluating now; that should be reconciled before we treat version numbers as meaningful signals.
• Mitigating factor: Apache-2.0 and a small, well-bounded problem surface. If upstream disappears, vendoring or reimplementing is a day or two of work, not a re-platforming. The realistic worst case is "we own 300 lines of UTF-16 offset math," which is survivable.

Key questions for the spike.

1. Does it cover the full current entity taxonomy — bold, italic, underline, strikethrough, spoiler, blockquote and expandable_blockquote, code, pre with language, text_link, text_mention, custom_emoji, hashtag/cashtag/bot_command/url/email/phone_number?
2. Does it round-trip losslessly — text + entities → HTML → text + entities — for emoji, ZWJ sequences, regional-indicator flags, combining marks, CJK, and RTL runs?
3. What are its transitive dependencies? If it drags in AMPHP or MadelineProto internals, that is a disqualifier for a simple notification path and changes the cost calculus materially.
4. What PHP version constraint does it declare, and does it work on our pinned runtime?
5. Does it expose offset translation (given an edit to the text, remap existing entities) or only pure conversion? We need the former for message editing and for 4096-character splitting.
6. Is the parse direction strict or lenient on malformed markup from user input, and does it escape on the serialize direction?

Integration Approach

Stack fit. Laravel 10–12 on PHP 8.1+ with ext-mbstring (present in any standard runtime) is sufficient. No database, queue, cache, or filesystem involvement. Composer autoloading is the entire installation story; there is nothing to php artisan vendor:publish.

Placement in the codebase.

• app/Support/Telegram/TelegramEntityFormatter.php — the only class that imports the library's namespace.
• Interface FormatsTelegramText bound in AppServiceProvider, so tests and future swaps are trivial.
• Our own DTOs (FormattedMessage, EntitySpan) as the boundary type; the library's types never cross it.
• Used from exactly two call sites: the outbound notification channel (compose → entities) and the webhook ingestion path (entities → rich representation for storage/rendering).

Migration path. There is nothing to migrate from unless we already hand-roll offset math; if we do, this is a straight replacement behind the adapter with the old implementation retained as a fallback binding for one release. Land it behind a config flag (telegram.entities.driver = package|internal) so rollback is a config change rather than a deploy revert.

Compatibility and validation. The gating work is a golden-corpus test suite, not the integration itself: a fixture set of real messages — emoji, flags, ZWJ family sequences, CJK, Arabic/Hebrew, inline code with backticks, nested bold-italic, links at string boundaries — each asserted for round-trip equality and for correct offset arithmetic. This suite is the deliverable that de-risks the package and survives any future replacement.

Sequencing.

1. Day 1: install in a branch, resolve transitive deps, answer the six questions above.
2. Day 2–3: build the golden corpus and the adapter; assert round-trip and split correctness.
3. Day 4: wire into outbound messaging only (lower risk, we control the input).
4. Day 5: wire into inbound webhook parsing (higher risk, untrusted input).
5. Then: pin, document, and schedule the dependency review.

Do not start with the inbound path. Outbound failures are visible to us; inbound failures corrupt stored content.

Alternative to weigh explicitly. If the dependency audit comes back heavy, or if the answer to question 5 is "conversion only," the honest comparison is against a ~200-line internal helper (mb_convert_encoding($s, 'UTF-16LE', 'UTF-8') + length math, with htmlspecialchars for the serialize direction) plus league/commonmark if we need real HTML parsing. For a 27-star package, "vendor the idea, not the dependency" is a legitimate outcome and should be presented as such rather than as a failure of the spike.

Operational Impact

Maintenance. The code we own is small; the dependency we own is not something we control. Pin to an exact version in composer.json, keep composer audit and automated dependency PRs on it, and record the fork recipe in the repo README so any engineer can vendor it in an hour. Budget roughly a day per year of dependency upkeep, plus a day if we ever have to fork.

Support. No commercial support, no guaranteed issue response, and a single maintainer. Documentation will come from the source and README. The internal adapter's docblock and the golden-corpus suite are our real support artifacts — write them as though the library is already unmaintained, because the expected value of that assumption is high.

Scaling. Computation is O(n) per message with negligible constant; at any plausible notification volume this is noise next to the HTTP calls to Telegram. The scaling concern is correctness under volume, not throughput: every message is an independent conversion, so a bug in surrogate-pair handling becomes a systematic, high-frequency defect the moment it ships, and it will appear as corrupted formatting across every message containing an emoji.

Failure modes and mitigations.

• Offset drift — entities applied to the wrong substring after any text mutation (truncation, templating, localization). Mitigation: never store entities and text separately; recompute entities whenever text changes.
• Surrogate-pair splitting — cutting a 4096-character message mid-emoji corrupts the character or the entity. Mitigation: split using the library's offset model, never substr, and assert on the boundary.
• Entity nesting/overlap — Telegram rejects or mangles overlapping entities. Mitigation: validate before send; fail closed with a plain-text fallback rather than sending a 400.
• Injection on the serialize path — entity-to-HTML output rendered into an admin UI without escaping. Mitigation: treat generated HTML as untrusted at the render boundary.
• Silent no-op — the adapter swallows an exception and sends unstyled text. Acceptable for outbound, unacceptable for inbound parsing where it would persist malformed data. Set different failure policies per call site.

Ramp-up. Half a day for a competent PHP engineer to be productive, and roughly a day to be trustworthy with the offset model. The genuine risk is concentration: this will be understood by one person. Mitigate by making the golden corpus the shared artifact — tests transfer knowledge better than documentation here, and they are the thing that makes the build-vs-adopt decision reversible.

Recommendation. Adopt, but only behind an adapter, only after the golden corpus exists, and with the internal-implementation fallback priced and documented before the first commit lands. The package is technically a good fit for a real problem that is easy to get subtly wrong; the 27 stars mean we are accepting ownership of the code path regardless of who is listed as the author.