Telegram Logger Laravel Package

Technical Evaluation

Architecture fit

• telegram-logger is a Laravel logging channel: it plugs in behind Log::error()/Monolog, so it requires no changes to application code or to existing log call sites. Adoption cost is configuration, not refactoring.
• The v2.0.0 dependency change from laravel/framework to illuminate/support + illuminate/contracts is a genuine architectural improvement for a TPM: the package becomes composable in Laravel-adjacent contexts (Lumen-style or standalone Silex/Console apps using Illuminate components) and reduces dependency-resolution contention in large multi-package applications.
• Switching delivery from GET to POST removes log content from proxy/access logs — a meaningful reduction in the package's own security footprint.

Integration feasibility

• Install is standard Composer + vendor:publish --tag=telegram-logger-config. All settings are exposed via .env, which fits existing 12-factor secret management. No migration scripts, no schema, no queue worker required.
• The public API is explicitly unchanged, and an existing published config keeps working because every new key falls back to a safe default. That makes this a "config-only" upgrade for teams already on the required runtime.
• The hard floor of PHP 8.4+ / Laravel 13+ is the single real integration gate. For most organisations this is not a package decision but an alignment with the platform-upgrade roadmap; Composer resolving to 1.x on older runtimes is expected and safe.

Technical risk

Key questions

1. Which applications in the portfolio are on PHP 8.4 / Laravel 13 today, and what is the upgrade timeline for the rest?
2. Does anything downstream parse the Telegram message body (regex alerts, on-call tooling, log-scraping bots)? If so, who owns re-validating the new four-line layout?
3. What is the data-classification policy for shipping application logs to a third-party messaging platform, and does key-based redaction satisfy it or do we need a hard allow-list of context fields?
4. Is a cache store configured in every app that will enable dedupe_seconds / max_per_minute, and is it shared or per-app? Shared caches change dedupe semantics across environments.
5. Are bot tokens and chat IDs per-environment and per-application, or is everything funnelling into one chat?
6. What is the Telegram Bot API rate budget for the chat(s) in use, and what is the expected log volume at peak?

Integration Approach

Stack fit

• Fits any Laravel 13 application already using the standard logging.php channel stack; it is an additive channel, not a replacement for file/stdout/Sentry logging. Recommended posture is "second channel for high-severity events only," not a primary log sink.
• Because level is now validated at boot against PSR-3, misconfiguration fails fast and loudly rather than silently sending nothing — helpful for standardising a channel template across many repos.
• Works well as a low-cost alerting path for small teams and internal tools where a full observability vendor is overkill.

Migration path

1. Freeze 1.x for apps on PHP 8.2/8.3 or Laravel 12. Pin ^1.0 explicitly in composer.json so a routine composer update cannot accidentally attempt the major bump.
2. Pilot 2.x in one non-critical service on the target runtime, in a staging environment with throw_on_failure=true so delivery problems surface immediately instead of being swallowed.
3. Republish config with --force in the pilot, review the diff for new keys, and backfill values via .env rather than editing the published file — keeps config portable and secret-free.
4. Enable redact_keys deliberately: start from the shipped defaults and extend with the organisation's domain-specific sensitive fields (e.g. email, card, ssn, session_id).
5. Set max_per_minute and dedupe_seconds conservatively for the first two weeks, then tune against observed volume.
6. Roll out by fleet batches keyed to runtime version, not by application criticality — the constraint is the PHP/Laravel floor, not the app's importance.

Compatibility

• Public API unchanged and config forward-compatible: no code changes, no test rewrites.
• The config-republish step is optional in the strict sense but recommended, because the new features (redaction, flood protection, api_url, base_path, throw_on_failure) are only discoverable in the published file. Document the new keys in the internal runbook regardless.
• Note for teams behind a proxy or using a self-hosted Bot API: api_url is the only supported path and requires the proxy to accept POST.

Sequencing Runtime upgrade → package bump → config republish + .env extension → staging validation with throw_on_failure → layout review by whoever consumes chat output → production canary → fleet.

Operational Impact

Maintenance

• Low. The package is small, single-purpose, and now has 144 tests at 100% code and type coverage, PHPStan at max, Pint, Rector, and a CI matrix across PHP 8.4/8.5 and both dependency stabilities. That is a stronger quality signal than most packages of this size and materially lowers the "abandoned dependency" risk.
• The narrower illuminate/* dependency surface reduces the frequency of forced upgrades caused by unrelated Laravel releases.
• Ongoing TPM cost is periodic version-floor tracking, not code upkeep.

Support

• v2 fixes most of the classic support burdens: delivery failures were previously invisible (API response never read), so "why didn't I get an alert?" was undiagnosable. Reading the response, throw_on_failure, the plain-text retry on HTTP 400, and the actionable error when allow_url_fopen is disabled all convert silent failures into visible ones.
• Boot-time validation of level and the UTF-8 / MarkdownV2 escaping fixes remove a class of "message arrived mangled" tickets.
• Support runbook should still cover: invalid bot token, wrong chat ID, bot removed from group, and Telegram-side rate limiting.

Scaling

• Per-application volume is bounded by max_per_minute; this is the right control for a chat-based sink, where the real constraint is human attention and Telegram's own limits, not throughput.
• This package does not scale as a high-volume log sink and should not be positioned as one. For services emitting more than a few messages per minute, the correct pattern is severity filtering upstream (level set to error/critical) plus aggregation, with Telegram reserved for the pager-worthy subset.
• Dedupe reduces chat noise during incidents — the scenario where a single failing endpoint would otherwise emit hundreds of identical messages.
• Delivery is synchronous within the log call. High-frequency error paths will pay a network round-trip per message; flood protection mitigates the worst case but does not eliminate the latency coupling. Worth flagging for latency-sensitive request paths.

Failure modes

Ramp-up

• Engineer time: roughly half a day for the first integration (install, publish, .env, staging verification), and under an hour per subsequent app once a channel template and .env convention exist.
• No new conceptual model to learn beyond Laravel's existing logging channels; the release notes and the published config file are sufficient documentation for a mid-level engineer.
• TPM-level effort concentrates in three places: sequencing the runtime upgrade, owning the data-egress decision, and assigning an owner to re-validate the new message layout wherever chat output is consumed. None of these are engineering-heavy, but all three are easy to leave unowned.
• Verdict: worth adopting on the target runtime. The breaking changes are runtime-floor and cosmetics, not API; the reliability and observability fixes are substantial; and the residual risks are policy and sequencing questions rather than technical ones.