README

Полноценная библиотека для работы с Max Bot API и Mini App в Laravel.

Соответствует актуальной официальной документации:

Возможности

Полный набор методов Bot API (GET /me, PATCH /me, messages, chats, answers, uploads двухэтапно, subscriptions, updates, videos/{videoToken}).
Корректная валидация Mini App initData — двойной HMAC-SHA256 с ключом "WebAppData" и BOT_TOKEN, с проверкой свежести auth_date.
Конструктор inline-клавиатур со всеми типами кнопок MAX: callback, link, request_contact, request_geo_location, open_app, message, clipboard.
Middleware:
- max.auth — валидация Mini App;
- max.webhook — проверка заголовка X-Max-Bot-Api-Secret;
- max.admin — проверка списка администраторов.
Artisan-команды: max:test, max:set-webhook, max:webhook-info, max:delete-webhook.
Очереди: SendMessageJob, SendBroadcastJob (с учётом 30 rps лимита).
Типизированные DTO: User, Chat, Message, Update, Callback, BotCommand.
Расширенное исключение MaxException с getStatusCode(), getErrorCode(), getResponse().

Установка

composer require letoceiling-coder/max

Публикация конфига (необязательно — пакет работает с дефолтами):

php artisan vendor:publish --tag=max-config

Базовый .env:

MAX_BOT_TOKEN=your_bot_token_here
MAX_WEBHOOK_URL=https://your-domain.com/api/max/webhook
MAX_WEBHOOK_SECRET=some_long_secret_ABCdef_123
MAX_UPDATE_TYPES=message_created,message_callback,bot_started
MAX_MINI_APP_URL=https://your-domain.com
MAX_BOT_USERNAME=your_bot_username
MAX_ADMIN_IDS=123456789,987654321

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

Отправка сообщения

use LetoceilingCoder\Max\Max;

Max::send(123456789, 'Привет!');

Max::bot()->sendMessage(123456789, '**Жирный** текст', ['format' => 'markdown']);

Max::sendToUser(42, 'Сообщение пользователю напрямую');

Клавиатура

use LetoceilingCoder\Max\Max;

$kb = Max::keyboard()
    ->row()
        ->callback('Кнопка 1', 'btn1')
        ->callback('Кнопка 2', 'btn2')
    ->row()
        ->link('Открыть сайт', 'https://example.com')
        ->openApp('Открыть Mini App', 'https://app.example.com')
    ->row()
        ->clipboard('Скопировать промокод', 'PROMO2025')
    ->get();

Max::bot()->sendMessage($chatId, 'Выберите:', ['attachments' => [$kb]]);

Mini App

use LetoceilingCoder\Max\Max;

$initData = $request->header('X-Max-Init-Data');

if (Max::validateMiniApp($initData)) {
    $user = Max::getMiniAppUser($initData);
    $userId = $user['id'];
}

Или через готовый middleware:

// routes/api.php
Route::middleware(['max.auth'])->group(function () {
    Route::post('/api/me', function (\Illuminate\Http\Request $r) {
        return $r->input('max_user');
    });
});

Webhook

use LetoceilingCoder\Max\Max;

Max::bot()->subscribe(
    url: 'https://your-domain.com/api/max/webhook',
    updateTypes: ['message_created', 'message_callback', 'bot_started'],
    secret: env('MAX_WEBHOOK_SECRET'),
);

Контроллер обработчика:

use LetoceilingCoder\Max\Types\Update;

public function handle(\Illuminate\Http\Request $request)
{
    $update = Update::fromArray($request->all());

    if ($update->isMessageCreated() && $update->message?->hasText()) {
        // ...
    }
    if ($update->isCallback() && $update->callback) {
        \LetoceilingCoder\Max\Max::bot()->answerCallback(
            $update->callback->callbackId,
            ['notification' => 'Готово']
        );
    }

    return response()->json(['success' => true]);
}

На защиту маршрута добавьте middleware max.webhook.

Загрузка файлов (двухэтапная)

use LetoceilingCoder\Max\Max;

$result = Max::bot()->uploadImage('/path/to/photo.jpg');

Max::bot()->sendMessage($chatId, 'Фото', [
    'attachments' => [[
        'type' => 'image',
        'payload' => ['token' => $result['token']],
    ]],
]);

Для видео/аудио токен возвращается сразу, изображение/файл — после фактической загрузки.

Deeplink

use LetoceilingCoder\Max\Max;

$url = Max::deeplink('SupportBot', 'ref_summer2025');
// https://max.ru/SupportBot?start=ref_summer2025

Artisan-команды

php artisan max:test
php artisan max:set-webhook https://example.com/webhook --types=message_created,bot_started --secret=...
php artisan max:webhook-info
php artisan max:delete-webhook

Основные классы

Класс	Назначение
`LetoceilingCoder\Max\Max`	Статический фасад
`LetoceilingCoder\Max\Bot`	HTTP-обёртка над Bot API
`LetoceilingCoder\Max\MiniApp`	Валидация initData
`LetoceilingCoder\Max\Keyboard`	Конструктор клавиатур
`LetoceilingCoder\Max\Limits`	Константы лимитов
`LetoceilingCoder\Max\Validator`	Автовалидация данных
`LetoceilingCoder\Max\Types\*`	DTO (User, Chat, Message, Update, Callback, BotCommand)

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

use LetoceilingCoder\Max\Exceptions\MaxException;

try {
    Max::send($chatId, 'Hello');
} catch (MaxException $e) {
    report($e);
    if ($e->isRateLimited()) {
        // 429
    }
    logger()->error('Max API', [
        'status'  => $e->getStatusCode(),
        'code'    => $e->getErrorCode(),
        'message' => $e->getMessage(),
        'body'    => $e->getResponse(),
    ]);
}

Документация

src/README.md — полный справочник методов
src/SETUP.md — установка и настройка
src/LIMITS.md — лимиты и валидация
src/EXAMPLES.md — примеры использования
src/FEATURES.md — список всех возможностей пакета
CHANGELOG.md — история изменений

Тесты

composer install
composer test

Текущий статус: 22 теста, 180 проверок, все проходят (PHPUnit 11, PHP 8.3).

Лицензия

MIT — см. LICENSE.

letoceiling-coder / max

Maintainers

Package info

Statistics

Security