Implement a Telegram Bot API Client in Yii2: Dependency Injection, 429 Retries, and Logging

<?php

return [
    'adminEmail' => 'admin@example.com',
    'telegramBotToken' => '',
];

<?php

return [
    'telegramBotToken' => '1234567890:ABCdefGHIjklMNOpqrsTUVwxyZ123456789',
];

<?php

namespace app\components;

use Yii;
use yii\base\Component;
use yii\base\InvalidConfigException;
use yii\base\Exception;

class TelegramClient extends Component
{
    public string $botToken = '';
    public int $timeout = 10;
    public int $connectTimeout = 5;
    public int $maxRetries = 3;

    public function init(): void
    {
        parent::init();

        if (empty($this->botToken)) {
            throw new InvalidConfigException('The "botToken" property must be configured in TelegramClient.');
        }
    }

    /**
     * Executes a POST request to the Telegram Bot API.
     *
     * @param string $method API method (e.g., 'sendMessage', 'answerCallbackQuery')
     * @param array $payload Key-value payload parameters
     * @return array Decoded JSON response from Telegram
     * @throws Exception If cURL encounters a network error or retries are exhausted
     */
    public function sendRequest(string $method, array $payload = []): array
    {
        $url = sprintf('https://api.telegram.org/bot%s/%s', $this->botToken, $method);
        $attempts = 0;

        while ($attempts < $this->maxRetries) {
            $attempts++;
            $result = $this->executeCurl($url, $payload);

            if ($result['status'] === 200 && isset($result['response']['ok']) && $result['response']['ok'] === true) {
                return $result['response'];
            }

            // Check for Rate Limit (HTTP 429)
            if ($result['status'] === 429 || (isset($result['response']['error_code']) && $result['response']['error_code'] === 429)) {
                $retryAfter = $result['response']['parameters']['retry_after'] ?? 1;

                Yii::warning(
                    sprintf('Telegram Rate Limit reached on %s. Attempt %d/%d. Waiting %d seconds.', $method, $attempts, $this->maxRetries, $retryAfter),
                    __METHOD__
                );

                if ($attempts < $this->maxRetries) {
                    sleep((int) $retryAfter);
                    continue;
                }
            }

            // Log fatal error details if request failed completely
            Yii::error(
                sprintf(
                    "Telegram API Request Failed.
Method: %s
HTTP Status: %d
Payload: %s
Response: %s",
                    $method,
                    $result['status'],
                    json_encode($payload, JSON_UNESCAPED_UNICODE),
                    json_encode($result['response'], JSON_UNESCAPED_UNICODE)
                ),
                __METHOD__
            );

            return $result['response'] ?? ['ok' => false, 'error_code' => $result['status'], 'description' => 'Unknown HTTP Error'];
        }

        throw new Exception(sprintf('Telegram API call "%s" failed after %d attempts.', $method, $this->maxRetries));
    }

    private function executeCurl(string $url, array $payload): array
    {
        $ch = curl_init();

        $jsonPayload = json_encode($payload);

        curl_setopt_array($ch, [
            CURLOPT_URL => $url,
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => $jsonPayload,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => [
                'Content-Type: application/json',
                'Content-Length: ' . strlen($jsonPayload),
            ],
            CURLOPT_TIMEOUT => $this->timeout,
            CURLOPT_CONNECTTIMEOUT => $this->connectTimeout,
            CURLOPT_SSL_VERIFYPEER => true,
        ]);

        $rawResponse = curl_exec($ch);
        $httpCode = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
        $curlErrno = curl_errno($ch);
        $curlError = curl_error($ch);

        curl_close($ch);

        if ($curlErrno !== 0) {
            Yii::error(sprintf('cURL execution error (%d): %s', $curlErrno, $curlError), __METHOD__);
            return [
                'status' => 0,
                'response' => ['ok' => false, 'description' => 'cURL Error: ' . $curlError],
            ];
        }

        $decoded = json_decode((string) $rawResponse, true);
        if (json_last_error() !== JSON_ERROR_NONE) {
            Yii::error(sprintf('Failed to parse Telegram JSON response: %s', json_last_error_msg()), __METHOD__);
            return [
                'status' => $httpCode,
                'response' => ['ok' => false, 'description' => 'Malformed JSON response'],
            ];
        }

        return [
            'status' => $httpCode,
            'response' => $decoded,
        ];
    }
}

$params = require __DIR__ . '/params.php';
if (file_exists(__DIR__ . '/params-local.php')) {
    $params = array_merge($params, require __DIR__ . '/params-local.php');
}

$config = [
    'id' => 'basic',
    'basePath' => dirname(__DIR__),
    'components' => [
        // Standard components...
    ],
    'container' => [
        'singletons' => [
            \app\components\TelegramClient::class => [
                'class' => \app\components\TelegramClient::class,
                'botToken' => $params['telegramBotToken'],
                'timeout' => 12,
                'maxRetries' => 3,
            ],
        ],
    ],
    'params' => $params,
];

return $config;

<?php

namespace app\controllers;

use Yii;
use yii\web\Controller;
use yii\web\Response;
use app\components\TelegramClient;

class NotificationController extends Controller
{
    private TelegramClient $telegram;

    // Inject TelegramClient through Constructor Injection
    public function __construct($id, $module, TelegramClient $telegram, $config = [])
    {
        $this->telegram = $telegram;
        parent::__construct($id, $module, $config);
    }

    public function actionSendSystemAlert(string $chatId, string $userInputName): Response
    {
        // Sanitize untrusted input to avoid breaking Telegram HTML parser
        $safeName = htmlspecialchars($userInputName, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');

        $messageText = sprintf(
            "<b>System Notification</b>
User <i>%s</i> triggered a critical alert.",
            $safeName
        );

        $payload = [
            'chat_id' => $chatId,
            'text' => $messageText,
            'parse_mode' => 'HTML',
            'disable_web_page_preview' => true,
        ];

        $response = $this->telegram->sendRequest('sendMessage', $payload);

        if (isset($response['ok']) && $response['ok'] === true) {
            return $this->asJson([
                'success' => true,
                'message_id' => $response['result']['message_id'],
            ]);
        }

        return $this->asJson([
            'success' => false,
            'error' => $response['description'] ?? 'Failed to deliver Telegram message.',
        ]);
    }
}