Download the PHP package webtolk/max without Composer

MAX PHP SDK

webtolk/max — framework-agnostic PHP SDK для MAX Platform API с архитектурой facade + modules + request objects + entities.

Что умеет SDK

• работать на PHP 8.1+
• принимать любой PSR-18 HTTP client
• использовать PSR-17 RequestFactoryInterface и StreamFactoryInterface
• отдавать типизированные модули bots, chats, messages, uploads, subscriptions, updates
• сериализовать payload/query объекты без ручной сборки массивов по всему проекту
• гидрировать ответы API в entity-объекты вместо сырых массивов

Установка

Минимальная установка самой библиотеки:

Установка вместе со всеми необходимыми библиотеками. HTTP-клиент может быть любой: Guzzle, Joomla, Symfony и т.д.

Runtime requirements:

• php >= 8.1
• ext-json
• ext-mbstring
• ext-pcre

Важно: SDK не создаёт transport сам. До первого вызова любого модуля нужно передать HTTP client и PSR-17 фабрики через Max::setTransport().

Quick Start

Пример ниже показывает типичный старт с Joomla HTTP Client.

Как это устроено

1. MaxConfig хранит токен и дополнительные HTTP headers.
2. Max::setTransport() создаёт внутренний transport adapter.
3. Фасад Max отдаёт модуль: bots(), chats(), messages(), uploads(), subscriptions() или updates().
4. Модуль вызывает соответствующий request object.
5. Ответ MAX API гидрируется в entity-объект SDK.

Основные возможности

Bots

• bots()->me() — получить профиль текущего бота
• bots()->updateCommands() — заменить список команд бота (до 32 команд)

Chats

• chats()->list() — compatibility-метод GET /chats: changelog MAX объявляет его неподдерживаемым, но 2026-08-31 live API всё ещё возвращает список; для новых интеграций надёжнее сохранять chat_id из webhook events
• chats()->getById() — карточка чата
• chats()->getByLink() — карточка публичного канала по совместимой публичной ссылке канала
• chats()->members() — участники
• chats()->memberMe() — текущий участник
• chats()->admins() — администраторы
• chats()->update() — изменение названия, описания, иконки и pinned message
• chats()->delete() — compatibility-удаление чата; endpoint принял безопасный live-запрос 2026-08-31, но отсутствует в части официальной навигации
• chats()->getPinnedMessage() — чтение закреплённого сообщения
• chats()->pin() — закрепление сообщения
• chats()->unpin() — снятие закрепления
• chats()->addMembers() — добавление участников
• chats()->removeMember() — удаление участника
• chats()->leave() — выход бота из чата
• chats()->addAdmins() — назначение администраторов
• chats()->removeAdmin() — снятие прав администратора
• chats()->sendAction() — отправка typing/photo/video/audio/file/seen action

Messages

• messages()->sendToChat() — отправка в чат
• messages()->sendToUser() — отправка пользователю
• messages()->getById() — чтение через GET /messages/{messageId}
• messages()->getByQueryId() — совместимое чтение через GET /messages?message_ids[]=...
• messages()->list() — выборка сообщений
• messages()->edit() — редактирование
• messages()->delete() — удаление
• messages()->sendComment() — отправка комментария к посту канала
• messages()->listComments() — список комментариев к посту
• messages()->getComment() — чтение отдельного комментария
• messages()->editComment() — редактирование комментария
• messages()->deleteComment() — удаление комментария
• messages()->answerCallback() — callback answer с optional disable_link_preview

Uploads

• uploads()->create() — получить upload URL
• uploads()->getVideo() — получить метаданные видео по токену
• uploads()->pushBinary() — отправить бинарные данные на upload host по UploadUrl, полученному из uploads()->create()
• uploads()->upload() — пройти весь upload flow одним вызовом

Subscriptions и Updates

• subscriptions()->list(), create(), delete()
• updates()->list() для long polling

JSON Schemas

Публичный репозиторий содержит обезличенный schema pack:

• docs/api-schemas/index.json
• docs/api-schemas/methods/*.schema.json

Эти файлы нужны как публичный reference layer для формы запросов и ответов. Все чувствительные значения в schema/examples маскируются как XXXX.

Что важно учитывать

• До вызова setTransport() модули использовать нельзя.
• По умолчанию SDK использует https://platform-api2.max.ru.
• messages()->getById() использует прямой endpoint GET /messages/{messageId}.
• Для старого query-based lookup используйте messages()->getByQueryId().
• Для channel posts не передавайте NewMessageBody::withNotify(false): live smoke на канале вернул errors.send-message.channel-notify; без поля notify отправка постов, кнопок и вложений проходит.
• Для audio и video после успешной загрузки возможен временный attachment.not.ready.
• Для messages.answerCallback() в публичном schema pack уже есть подтверждённый success example.
• События комментариев можно передавать в GetUpdatesQuery::withTypes() и CreateSubscriptionPayload строками comment_created, comment_edited и comment_removed.

Тестирование

В публичном репозитории сохранены:

• unit tests в tests/Unit/**
• PHPUnit config в phpunit.xml
• обезличенные API schemas в docs/api-schemas/**

Запуск unit tests:

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

• Индекс документации
• Быстрый старт
• Интеграция с Joomla HTTP Client
• Типовые сценарии
• Фасад и методы модулей
• Payload-объекты
• Attachment-объекты
• Query-объекты
• Сущности
• Ошибки и edge cases
• Тестирование
• Обезличенные ответы MAX API