Optimize Telegram Bot File Uploads in PHP with CURLFile and file_id Reuse

<?php

/**
 * Uploads a local file to Telegram as a document.
 *
 * @param string $chatId The recipient chat ID.
 * @param string $filePath Absolute path to the local file.
 * @param string $caption Optional caption for the document.
 * @return string The Telegram file_id of the uploaded file.
 * @throws Exception If the upload fails or the API returns an error.
 */
function sendLocalDocument(string $chatId, string $filePath, string $caption = ''): string
{
    $token = getenv('TELEGRAM_BOT_TOKEN');
    if (!$token) {
        throw new Exception('Telegram bot token is not configured in environment variables.');
    }

    if (!file_exists($filePath) || !is_readable($filePath)) {
        throw new Exception("File not found or not readable: {$filePath}");
    }

    $url = "https://api.telegram.org/bot{$token}/sendDocument";

    // Detect MIME type dynamically
    $mimeType = mime_content_type($filePath) ?: 'application/octet-stream';
    $postName = basename($filePath);

    $payload = [
        'chat_id' => $chatId,
        'document' => new CURLFile($filePath, $mimeType, $postName),
    ];

    if ($caption !== '') {
        $payload['caption'] = $caption;
    }

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    // Set a generous timeout for large file uploads
    curl_setopt($ch, CURLOPT_TIMEOUT, 60);
    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10);

    $response = curl_exec($ch);

    if ($response === false) {
        $error = curl_error($ch);
        $errno = curl_errno($ch);
        curl_close($ch);
        throw new Exception("cURL error ({$errno}): {$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 Exception('Failed to parse Telegram API JSON response.');
    }

    if ($httpCode !== 200 || !isset($data['ok']) || $data['ok'] !== true) {
        $description = $data['description'] ?? 'Unknown error';
        throw new Exception("Telegram API error (HTTP {$httpCode}): {$description}");
    }

    // Return the file_id for database caching
    return $data['result']['document']['file_id'];
}

<?php

/**
 * Sends a document using a public URL or a cached file_id.
 *
 * @param string $chatId The recipient chat ID.
 * @param string $fileIdentifier A public URL or a Telegram file_id.
 * @param string $caption Optional caption.
 * @return string The Telegram file_id.
 * @throws Exception If the request fails.
 */
function sendExistingDocument(string $chatId, string $fileIdentifier, string $caption = ''): string
{
    $token = getenv('TELEGRAM_BOT_TOKEN');
    if (!$token) {
        throw new Exception('Telegram bot token is not configured.');
    }

    $url = "https://api.telegram.org/bot{$token}/sendDocument";

    $payload = [
        'chat_id' => $chatId,
        'document' => $fileIdentifier,
    ];

    if ($caption !== '') {
        $payload['caption'] = $caption;
    }

    $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_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_TIMEOUT, 15);

    $response = curl_exec($ch);

    if ($response === false) {
        $error = curl_error($ch);
        curl_close($ch);
        throw new Exception("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 Exception('Failed to parse Telegram API JSON response.');
    }

    if ($httpCode !== 200 || !isset($data['ok']) || $data['ok'] !== true) {
        $description = $data['description'] ?? 'Unknown error';
        throw new Exception("Telegram API error (HTTP {$httpCode}): {$description}");
    }

    return $data['result']['document']['file_id'];
}