Send Telegram Messages via cURL in PHP with Robust Error Handling

<?php

declare(strict_types=1);

/**
 * Sends a message to a Telegram chat via the Bot API.
 *
 * @param string $token The Telegram Bot token.
 * @param int|string $chatId The target chat ID.
 * @param string $text The message text.
 * @param string $parseMode The formatting mode (HTML, MarkdownV2, etc.).
 * @return array The decoded Telegram response.
 * @throws RuntimeException If the request fails, times out, or Telegram returns an error.
 */
function sendTelegramMessage(string $token, int|string $chatId, string $text, string $parseMode = 'HTML'): array
{
    $url = "https://api.telegram.org/bot" . $token . "/sendMessage";

    $payload = [
        'chat_id' => $chatId,
        'text' => $text,
        'parse_mode' => $parseMode,
    ];

    $ch = curl_init();

    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    // Prevent the script from hanging indefinitely
    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
    curl_setopt($ch, CURLOPT_TIMEOUT, 10);

    $response = curl_exec($ch);

    if ($response === false) {
        $error = curl_error($ch);
        curl_close($ch);
        throw new RuntimeException("cURL Error: " . $error);
    }

    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $data = json_decode($response, true);
    if (json_last_error() !== JSON_ERROR_NONE) {
        throw new RuntimeException(
            "Failed to decode JSON response. Raw response: " . $response . ". JSON Error: " . json_last_error_msg()
        );
    }

    if (!isset($data['ok']) || $data['ok'] !== true) {
        $description = $data['description'] ?? 'Unknown error';
        $errorCode = $data['error_code'] ?? $httpCode;
        throw new RuntimeException("Telegram API Error [{$errorCode}]: {$description}", $errorCode);
    }

    return $data;
}

<?php

require_once 'telegram_helper.php';

// Retrieve the token from environment variables
$token = getenv('TELEGRAM_BOT_TOKEN');
$chatId = getenv('TELEGRAM_CHAT_ID');

if (!$token || !$chatId) {
    die("Configuration error: TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID must be set.\n");
}

// Dynamic user input that might contain special characters
$userInput = "User <John&Doe> Testing";

// Escape the input safely for HTML parse_mode
$safeInput = htmlspecialchars($userInput, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML5, 'UTF-8');

$message = "<b>System Alert</b>\n";
$message .= "Status: <i>Active</i>\n";
$message .= "Payload: <code>" . $safeInput . "</code>";

try {
    $result = sendTelegramMessage($token, $chatId, $message, 'HTML');
    echo "Message sent successfully. Message ID: " . $result['result']['message_id'] . "\n";
} catch (RuntimeException $e) {
    echo "Error sending message: " . $e->getMessage() . "\n";
}