PHPackages                             letoceiling-coder/max - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. letoceiling-coder/max

ActiveLibrary[API Development](/categories/api)

letoceiling-coder/max
=====================

Laravel package for Max Bot API and Mini App integration (https://dev.max.ru)

v2.0.0(2mo ago)26MITPHPPHP ^8.2

Since Dec 4Pushed 2mo agoCompare

[ Source](https://github.com/letoceiling-coder/max)[ Packagist](https://packagist.org/packages/letoceiling-coder/max)[ RSS](/packages/letoceiling-coder-max/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (12)Versions (3)Used By (0)

Max Bot API для Laravel
=======================

[](#max-bot-api-для-laravel)

[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)[![PHP Version](https://camo.githubusercontent.com/c5e8da782b1a0673c08b4f474108036d2cc973470eed2d5d89d48e8c8475eee6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344382e322d626c75652e737667)](https://www.php.net/)

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

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

- [Max API](https://dev.max.ru/docs-api)
- [Mini Apps / MAX Bridge](https://dev.max.ru/docs/webapps/bridge)
- [Валидация initData](https://dev.max.ru/docs/webapps/validation)
- [Разработка ботов](https://dev.max.ru/docs/chatbots/bots-coding/prepare)
- [FAQ / Help](https://dev.max.ru/help)

Возможности
-----------

[](#возможности)

- Полный набор методов 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

[](#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

[](#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

[](#deeplink)

```
use LetoceilingCoder\Max\Max;

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

### Artisan-команды

[](#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/README.md) — полный справочник методов
- [src/SETUP.md](src/SETUP.md) — установка и настройка
- [src/LIMITS.md](src/LIMITS.md) — лимиты и валидация
- [src/EXAMPLES.md](src/EXAMPLES.md) — примеры использования
- [src/FEATURES.md](src/FEATURES.md) — список всех возможностей пакета
- [CHANGELOG.md](CHANGELOG.md) — история изменений

Тесты
-----

[](#тесты)

```
composer install
composer test
```

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

Лицензия
--------

[](#лицензия)

MIT — см. [LICENSE](LICENSE).

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance86

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~136 days

Total

2

Last Release

75d ago

Major Versions

1.0.0 → v2.0.02026-04-20

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/241832926?v=4)[letoceiling-coder](/maintainers/letoceiling-coder)[@letoceiling-coder](https://github.com/letoceiling-coder)

---

Top Contributors

[![Postads](https://avatars.githubusercontent.com/u/25578332?v=4)](https://github.com/Postads "Postads (4 commits)")

---

Tags

apilaravelbotMessengermaxmini-app

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/letoceiling-coder-max/health.svg)

```
[![Health](https://phpackages.com/badges/letoceiling-coder-max/health.svg)](https://phpackages.com/packages/letoceiling-coder-max)
```

###  Alternatives

[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9762.4M131](/packages/roots-acorn)[api-platform/laravel

API Platform support for Laravel

58171.5k14](/packages/api-platform-laravel)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k15.1M132](/packages/laravel-pulse)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

77022.3M151](/packages/laravel-mcp)[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[nuwave/lighthouse

A framework for serving GraphQL from Laravel

3.5k11.8M117](/packages/nuwave-lighthouse)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)