README

PHP SDK для работы с API мессенджера MAX. Этот пакет предоставляет удобный интерфейс для взаимодействия с MAX Bot API.

Установка

Установите пакет через Composer:

composer require targethunter/max-php-sdk

Требования

• PHP 7.4 или выше
• GuzzleHttp 7.5 или выше
• Расширение JSON

Быстрый старт

Инициализация клиента

<?php

use TH\MAX\Client\MAXClient;
use TH\MAX\Client\Request\MAXRequest;

// Создаем клиент с вашим access_token
$accessToken = 'ваш_access_token_здесь';
$request = new MAXRequest($accessToken);
$client = new MAXClient($request);

// Теперь вы можете использовать все модули API

Получение информации о боте

// Получить информацию о текущем боте
$bot = $client->bots()->getMe();
echo "Имя бота: " . $bot->name;
echo "Описание: " . $bot->description;

Миграция на v2.0.0

Версия v2.0.0 приводит публичный API SDK к актуальной документации MAX API.

Breaking changes:

• Удален Chats::getAll(): метод GET /chats больше не поддерживается MAX API. Получайте chat_id через Webhook-подписки или Long Polling в окружениях разработки.
• Удален Chats::delete(): метод DELETE /chats/{chatId} отсутствует в актуальной документации MAX API.
• Удален Bots::update(): метод PATCH /me отсутствует в актуальной документации MAX API.

Новые возможности:

• UploadTypes содержит документированные типы загрузки: image, video, audio, file.
• ClipboardButton добавляет кнопку inline-клавиатуры с типом clipboard.
• WebhookSecretVerifier помогает проверить заголовок X-Max-Bot-Api-Secret.

Модули API

SDK разделен на несколько модулей, для удобства использования. Модули реализованы так же, как в официальном API MAX.

1. Модуль Bots (Боты)

Управление информацией о боте.

Примеры:

// Получить информацию о боте
$bot = $client->bots()->getMe();
echo "ID бота: " . $bot->id;
echo "Имя: " . $bot->name;

2. Модуль Messages (Сообщения)

Работа с сообщениями.

Примеры:

// Отправить текстовое сообщение
$message = $client->messages()->send(
    user_id: 12345,
    text: 'Привет! Это тестовое сообщение от бота.'
);

// Отправить сообщение в чат
$message = $client->messages()->send(
    chat_id: 67890,
    text: 'Сообщение в групповой чат'
);

// Получить список сообщений
$messages = $client->messages()->getAll(
    chat_id: 67890,
    count: 20
);

// Обновить сообщение
$result = $client->messages()->update(
    message_id: 'message_123',
    text: 'Обновленный текст сообщения'
);

// Удалить сообщение
$result = $client->messages()->delete('message_123');

// Получить сообщение по ID
$message = $client->messages()->getById('message_123');

3. Модуль Chats (Чаты)

Управление чатами и участниками.

Примеры:

// Получить чат по ID
$chat = $client->chats()->getById(12345);
echo "Название чата: " . $chat->title;

// Обновить информацию о чате
$updatedChat = $client->chats()->update(
    chat_id: 12345,
    title: 'Новое название чата',
    notify: true
);

// Получить список участников
$members = $client->chats()->getMembers(
    chat_id: 12345,
    count: 20
);

// Добавить участников в чат
$result = $client->chats()->addMembers(
    chat_id: 12345,
    user_ids: [111, 222, 333]
);

// Закрепить сообщение
$result = $client->chats()->pinMessage(
    chat_id: 12345,
    message_id: 'message_123',
    notify: true
);

4. Модуль Upload (Загрузка файлов)

Загрузка файлов в MAX.

Примеры:

use TH\MAX\Config\UploadTypes;

// Получить URL для загрузки изображения
$uploadUrl = $client->upload()->getUrl(UploadTypes::IMAGE);
echo "URL для загрузки: " . $uploadUrl->url;

// Получить URL для загрузки файла
$uploadUrl = $client->upload()->getUrl('file');

5. Модуль Subscriptions (Подписки)

Управление webhook подписками.

Для production-окружения MAX рекомендует использовать Webhook. Long Polling через getUpdates() оставлен в SDK, потому что метод документирован, но его стоит использовать только для разработки и тестирования.

Webhook endpoint должен использовать HTTPS, доверенный сертификат и порт 443. Если при подписке указан secret, проверяйте входящий заголовок X-Max-Bot-Api-Secret.

Примеры:

// Получить список подписок
$subscriptions = $client->subscriptions()->getAll();

// Создать подписку на webhook
$result = $client->subscriptions()->subscribe(
    url: 'https://your-domain.com/webhook',
    update_types: ['message', 'chat_member'],
    secret: 'your_secret_key'
);

// Удалить подписку
$result = $client->subscriptions()->unsubscribe(
    url: 'https://your-domain.com/webhook'
);

// Получить обновления
$updates = $client->subscriptions()->getUpdates(
    limit: 100,
    timeout: 30
);

use TH\MAX\Webhook\WebhookSecretVerifier;

$isValid = WebhookSecretVerifier::verifyFromHeaders(
    getallheaders(),
    'your_secret_key'
);

Обработка ошибок

SDK автоматически обрабатывает ошибки от API MAX и преобразует их в читаемый формат. Все методы могут выбрасывать исключения MAXHttpException при ошибках сети или API.

Автоматическая обработка ошибок

SDK автоматически:

• Извлекает человекочитаемые сообщения об ошибках из ответов API
• Сохраняет HTTP статус код
• Сохраняет оригинальное исключение Guzzle для отладки

use TH\MAX\Exceptions\MAXHttpException;

try {
    $message = $client->messages()->send(
        user_id: 12345,
        text: 'Тестовое сообщение'
    );
    echo "Сообщение отправлено: " . $message->id;
} catch (MAXHttpException $e) {
    echo "Ошибка API: " . $e->getMessage();
    echo "HTTP код: " . $e->getCode();
    
    // Получить оригинальное исключение Guzzle для отладки
    if ($e->hasOriginalException()) {
        $original = $e->getOriginalException();
    }
    // Или через стандартную цепочку исключений
    $previous = $e->getPrevious();
}

Типы ошибок

SDK обрабатывает различные форматы ошибок от MAX API:

• message - основное сообщение об ошибке
• error.message - сообщение в объекте error
• error.description - описание ошибки
• description - альтернативное поле описания

Если ответ не в формате JSON, SDK вернет сырое тело ответа.

Конфигурация

Базовый URL API

По умолчанию SDK использует базовый URL API: https://platform-api2.max.ru/

Начиная с версии v1.3.0, SDK по умолчанию использует platform-api2.max.ru, как указано в актуальной документации MAX API.

Документация MAX указывает лимит для platform-api2.max.ru: до 30 запросов в секунду.

Кастомный HTTP клиент

Вы можете создать собственный HTTP клиент и передать его в конструктор MAXRequest:

use GuzzleHttp\Client;

$customClient = new Client([
    'timeout' => 30,
    'verify' => false, // Отключить проверку SSL (не рекомендуется для продакшена)
]);

$request = new MAXRequest($accessToken, $customClient);
$client = new MAXClient($request);

Кастомизация через наследование

Вы можете унаследоваться от MAXRequest и переопределить нужные методы:

Кастомный URL API

use TH\MAX\Client\Request\MAXRequest;

class CustomMAXRequest extends MAXRequest
{
    protected function getURL(string $method): string
    {
        return 'https://api.max.ru/v2/' . ltrim($method, '/');
    }
}

Кастомный класс исключений

Метод createException() — фабрика для создания исключений. Переопределите его, чтобы SDK бросал ваши доменные исключения вместо MAXHttpException:

use GuzzleHttp\Exception\GuzzleException;
use TH\MAX\Client\Request\MAXRequest;

class AppMAXRequest extends MAXRequest
{
    protected function createException(string $message, int $code, GuzzleException $original): \Throwable
    {
        // Бросаем ваше доменное исключение вместо MAXHttpException
        return new \App\Exceptions\ApiException($message, $code, $original);
    }
}

Логика парсинга ответа API (извлечение человекочитаемого сообщения из JSON) остаётся в SDK — вы получаете готовое сообщение в параметре $message.

Полный пример использования

<?php

require_once 'vendor/autoload.php';

use TH\MAX\Client\MAXClient;
use TH\MAX\Client\Request\MAXRequest;
use TH\MAX\Exceptions\MAXHttpException;

// Инициализация
$accessToken = 'ваш_access_token';
$request = new MAXRequest($accessToken);
$client = new MAXClient($request);

try {
    // Получить информацию о боте
    $bot = $client->bots()->getMe();
    echo "Бот: " . $bot->name . "\n";

    // Отправить сообщение в известный чат
    $message = $client->messages()->send(
        chat_id: 12345,
        text: 'Привет из PHP SDK!'
    );
    echo "Сообщение отправлено с ID: " . $message->id . "\n";
    
} catch (MAXHttpException $e) {
    echo "Ошибка API MAX: " . $e->getMessage() . "\n";
    echo "HTTP код: " . $e->getCode() . "\n";
} catch (Exception $e) {
    echo "Общая ошибка: " . $e->getMessage() . "\n";
}

Лицензия

MIT License

Поддержка

Если у вас есть вопросы или проблемы, создайте issue в репозитории проекта.