Telegram Logger Laravel Package

Product Decisions This Supports

• Incident visibility / on-call readiness. With v2.0.0's fixed delivery-failure surfacing, dedupe/flood protection, and plain-text retry, this package becomes a credible fast path for pushing production errors into a Telegram chat. That maps directly to a "do we need PagerDuty/Opsgenie yet?" decision — for small teams or side products, a hardened Telegram sink can defer a paid alerting vendor by months.
• Build vs. buy for alerting. The package is a thin, single-purpose transport, not an alerting platform. It answers the "build" side of "custom error-notification channel" decisions and is a reasonable stopgap while evaluating Sentry, Bugsnag, or Grafana OnCall. Judge it as a transport layer, not as incident management.
• Multi-app / multi-tenant portfolio monitoring. The new compact heading (❌ ERROR | Shop | production) makes one Telegram chat legible across several applications and environments — a real enabler for agencies or platform teams running many small Laravel apps who want one shared feed instead of N dashboards.
• Security & compliance posture. redact_keys with nested-array support plus POST-instead-of-GET (so log content no longer leaks into proxy/access logs) materially changes the risk conversation. This is the release that lets a PM say "yes, we can send production error context to a third party" without a redaction service bolted on — provided the team configures redact_keys deliberately.
• Roadmap sequencing for the observability backlog. Because the package now fails loudly (throw_on_failure) and surfaces API errors, a team can decide to start with Telegram logging now and migrate to structured observability later, without the migration being a rewrite — logging calls are unchanged (Log::error() behaves as before).
• Developer-experience and local-development decisions. throw_on_failure makes misconfiguration obvious in dev/staging; api_url supports proxies or self-hosted Bot API for teams with egress restrictions. Both reduce the "works on my machine / silent in prod" class of incidents.
• Upgrade/planning decisions. The floor is now PHP 8.4+ and Laravel 13+. That's a genuine portfolio-planning input: this package cannot be adopted by teams still on Laravel 12, and adopting it becomes a forcing function (or a blocker) for the platform-upgrade roadmap.

When to Consider This Package

Consider it when:

• You run one or more Laravel 13+ applications on PHP 8.4+ and want error/exception notifications in a chat tool without standing up an alerting vendor.
• You need low-effort, low-cost visibility for a small team, internal tool, side project, or staging environment where a full APM/alerting stack is overkill.
• Your team already lives in Telegram and wants alerts where the conversation happens, rather than in another dashboard nobody checks.
• You have multiple apps or environments posting to one chat and need the source identifiable at a glance (the v2.0.0 heading layout is designed exactly for this).
• You must send context payloads that may contain secrets and need built-in redaction rather than a custom scrubber.
• You are noisy by nature (retry loops, cron failures, high-traffic endpoints) and need dedupe/rate-limiting so the channel stays usable — dedupe_seconds and max_per_minute are the reason to pick this over a naive Monolog handler.
• You operate behind a proxy or self-hosted Bot API — api_url and the switch to POST make this viable where GET-based alternatives would leak payloads into access logs.
• You want loud failures in development (throw_on_failure) and silent resilience in production.

Look elsewhere when:

• You are on Laravel 12 or PHP 8.2/8.3 — Composer will correctly keep you on 1.x, so this release is not an option until you upgrade. Don't let anyone interpret the version pin as a broken update.
• You need acknowledgement, escalation policies, on-call rotations, or uptime SLAs. Telegram is best-effort and rate-limited by Telegram itself; this package is not an incident-management system and should not be sold internally as one.
• You require auditable, durable log retention or compliance-grade storage. Chat messages are not a system of record.
• Your message volume or sensitivity demands structured tracing, sampling, or PII classification — you want a real observability backend.
• You need guaranteed delivery. Flood protection intentionally drops duplicate messages; that is the right trade-off for chat alerts but wrong for anything you must not lose.
• You want a vendor-supported dependency with a commercial SLA — this is a single-maintainer open-source package. The 144 tests, 100% coverage, PHPStan max, and CI matrix are reassuring, but they are not a support contract.

How to Pitch It (Stakeholders)

For executives: This is a small, free Laravel package that sends application errors to a Telegram chat. The v2.0.0 release is the first version we can responsibly put in front of production traffic: it fixes cases where alerts were silently lost, stops malformed messages from crashing the application, redacts secrets like passwords and tokens before anything leaves our servers, and rate-limits noise so the channel stays readable. It also stops putting log content into proxy access logs. In short: the alerting path is now trustworthy, inexpensive, and low-risk — a sensible interim step before committing budget to a commercial observability platform.

For engineering leads: The public API is unchanged — Log::error() and friends behave exactly as before — so adoption is a config-and-deploy, not a refactor. The real engineering value is the bug-fix list: byte-vs-character truncation that silently dropped long messages, exceptions thrown from inside the log listener that could take down the calling code, unread MarkdownV2 escaping of backslashes, and the fact that delivery failures were previously indistinguishable from success. Those are exactly the failure modes that make people stop trusting an alerting channel. Flood protection, nested redaction, and automatic plain-text retry on HTTP 400 are net-new resilience at no extra operational cost.

For the platform/upgrade conversation: The one real decision this release forces is the version floor — PHP 8.4+ and Laravel 13+. Teams on Laravel 12 stay on 1.x automatically; that's expected behaviour, not a broken update. So the question is simply: is our Laravel 13 upgrade on the roadmap, and does adopting this package give us a reason to bring it forward? Note also the config republish step (vendor:publish --tag=telegram-logger-config --force); an existing published config continues to work because every new setting falls back to a safe default, so this is an opt-in migration rather than a hard cutover.

Honest caveats to state up front: This is a single-maintainer package with no commercial support, and Telegram is best-effort with its own rate limits. Treat it as a transport for alerts, not as incident management, and not as a system of record. Set redact_keys deliberately rather than relying on defaults, and keep throw_on_failure limited to local/staging so production logging never becomes a source of outages.