Laravel Telegram Logger Laravel Package

Product Decisions This Supports

• Build vs. buy for alerting. This package is a "buy" (well, adopt) answer to the question "do we pay for Sentry/Datadog/Papertrail, or do we push critical errors into a chat we already live in?" For a Laravel-only stack, adopting this removes a meaningful chunk of the build side of that decision — dedup, grouping, rate limiting, retry/backoff, and message formatting are the parts teams underestimate when they say "we'll just write a Slack/Telegram notifier."
• Roadmap sequencing for incident response. Because the hard parts are already implemented (deduplication with occurred N× roll-up, error grouping by message/level+message/exception/callback, global + per-error rate limiting), this can ship in a sprint rather than a quarter. That makes "we have production error alerting" achievable before investing in full observability tooling.
• Cheap coverage for the tiers observability budgets usually miss. Staging, internal tools, admin panels, queue workers, scheduled commands, low-traffic client apps — these rarely justify a per-seat APM contract but do justify "post the exception to a chat." This package is priced correctly for that decision (free, self-hosted, one channel config).
• Reducing mean time to acknowledge. Routing per level and per forum topic, @username mentions, and silent levels for noisy-but-not-urgent events let you segment signal from noise deliberately — a product decision about who gets woken up, not just a logging decision.
• Compliance and data-handling decisions. Explicit redaction of keys and value patterns, plus unconditional bot-token masking, means you can make a defensible call about sending production error payloads to a third-party chat service. The stacktrace.txt attachment (replying to the message) keeps full fidelity available without blowing past Telegram's 4096-character message cap — a real constraint that shapes whether you enable this on high-stack-depth frameworks.
• Operational ownership decisions. Graceful no-op when token/chat id is missing means local and CI environments degrade silently to file logs with zero config branching — that's a decision not to maintain parallel logging configs per environment. The telegram-logger:test [--exception] command is the difference between "we think it's wired up" and a five-second smoke test in your runbook.
• Portfolio consistency. Being the explicit sibling of laravel-discord-logger (same production pipeline, different transport) is a signal that the maintainer is building a family of channels rather than one-offs — relevant if you're deciding whether to standardize alerting across several Laravel services.

When to Consider This Package

Strong fit when:

• You run Laravel 12.61+ or 13 on PHP 8.2+ and are willing to track recent framework versions. This is a hard gate — check your fleet's version floor before committing, and note Laravel 13 support implies the package must keep pace with framework releases.
• Telegram is already where your on-call or team actually reads messages. Adoption cost is near zero if the destination exists; it's a behavior change if it doesn't.
• You need actionable alerts, not a log archive. The dedup, grouping, and rate limiting are the standout features here — they're the difference between a channel people read and a channel people mute.
• Volume is moderate and bursty. Global rate limiting (default 20/min) plus per-error limits is a sensible guardrail, but it is a guardrail, not a firehose solution.
• You want fast, low-risk rollout: async delivery via queued job, retries with backoff on 5xx/unreachable, 429 handling that respects retry_after, 4xx fail-fast with Telegram's own description forwarded to a fallback channel. That failure taxonomy is unusually thought-through for a v1.
• Redaction matters. You're sending real production payloads to a third party and need key/pattern-based scrubbing built in rather than bolted on.

Look elsewhere when:

• You need searchable logs, dashboards, trends, or alert routing rules beyond level → chat. This is a notification pipe, not observability. It complements Sentry/Datadog; it does not replace them.
• Telegram is a non-starter for legal or IT policy reasons (data residency, blocked consumer messengers, corporate chat mandates). The sibling laravel-discord-logger is the obvious alternative; Slack and email channels are well-trodden in Laravel's ecosystem.
• You need vendor support, an SLA, or a security review package. This is a 1.0.0 first release from a single maintainer with no release history to assess. Maturity, long-term maintenance, and API stability are unproven. Budget for the possibility of forking.
• Your volume is genuinely high (thousands of errors per minute during incidents). Dedup and rate limiting will help, but you'll be leaning on the occurred N× roll-up to reconstruct what happened, and Telegram's per-chat limits become the ceiling. Structured log storage should be the primary system; this should be the pager.
• You're not on Laravel, or you're pinned to Laravel 11 or below. There's no polyfill path here.
• You need per-user or per-tenant routing. Routing is per level and per forum topic — useful, but it's not a rules engine.

Adoption checklist before you commit: confirm PHP/Laravel version floors across services; confirm who owns the bot token and chat/topic IDs as secrets; decide the level→chat matrix and which levels are silent; decide whether @username mentions are acceptable (they're effective and they're also a good way to annoy people); verify redaction patterns against a sample of real exception payloads; run telegram-logger:test --exception in staging, not production.

How to Pitch It (Stakeholders)

To executives: We can have production error alerting landing in a channel the team already monitors, this sprint, at no licence cost. It's a single Laravel package with sensible defaults — it de-duplicates repeated errors, groups related ones, and rate-limits itself so the channel stays readable rather than becoming noise people mute. It handles the unglamorous reliability work (queued delivery, retry with backoff, graceful handling of API failures) that we would otherwise build and maintain ourselves. It's a targeted improvement to how fast we notice and respond to incidents, not a replacement for our observability spend — think of it as closing the gap on the environments and services that don't justify a paid APM contract.

To engineering: Drop-in Laravel log channel over the Telegram Bot API, async via queued job. Retries on 5xx/unreachable with backoff, honours retry_after on 429, fails fast on 4xx and reports Telegram's description to a fallback channel. HTML messages with Exception/Request/Livewire/Job/Command/Stacktrace/Context/Extra sections, clamped to 4096 chars, with the full stacktrace attached as stacktrace.txt replying to the message. Dedup with occurred N× roll-up, error grouping by message, level+message, exception, or callback, plus global (default 20/min) and per-error rate limits. Per-level chats and forum topics, @username mentions, disable_notification for low-priority levels. Key and value-pattern redaction with bot tokens always masked. No-ops cleanly when token or chat id is absent, so local/CI need no special-casing. Smoke test: php artisan telegram-logger:test --exception.

To security/compliance: Payloads are scrubbed before they leave the process via configurable key and value-pattern redaction, and bot tokens are masked unconditionally. Data goes to Telegram, so the open question is policy, not implementation — that needs a yes/no before rollout, and it's the one item that can block the whole thing.

Caveats to state up front, not later: this is a 1.0.0 first release with no track record; PHP 8.2+ and Laravel 12.61+/13 are hard requirements; single-maintainer risk means we should be comfortable forking if it stalls; and it is a notification pipe, not a log store — we keep our existing logging and treat this as the alerting layer on top.