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-объекты вместо сырых массивов

Установка

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

composer require webtolk/max

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

composer require webtolk/max joomla/http laminas/laminas-diactoros

Runtime requirements:

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

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

Quick Start

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

<?php

declare(strict_types=1);

use Joomla\Http\HttpFactory as JoomlaHttpFactory;
use Laminas\Diactoros\RequestFactory;
use Laminas\Diactoros\StreamFactory;
use Webtolk\Max\Config\MaxConfig;
use Webtolk\Max\Max;
use Webtolk\Max\Payload\NewMessageBody;

require_once __DIR__ . '/vendor/autoload.php';

$token = 'YOUR_BOT_TOKEN';

$httpClient = (new JoomlaHttpFactory())->getHttp([
    'timeout' => 20,
]);

$max = new Max(new MaxConfig($token));

$max->setTransport(
    $httpClient,
    new RequestFactory(),
    new StreamFactory(),
);

$bot = $max->bots()->me();

echo 'Bot ID: ' . $bot->getId() . PHP_EOL;
echo 'Username: ' . $bot->getUsername() . PHP_EOL;

$message = $max->messages()->sendToChat(
    123456,
    NewMessageBody::text('Привет из MAX SDK')
);

echo 'Message text: ' . ($message->getBody()?->getText() ?? '') . PHP_EOL;

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

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() — получить профиль текущего бота

Chats

• chats()->list() — список чатов
• chats()->getById() — карточка чата
• chats()->members() — участники
• chats()->memberMe() — текущий участник
• chats()->admins() — администраторы
• chats()->update() — изменение названия, иконки и pinned message
• chats()->delete() — удаление чата
• 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() — чтение по message_ids
• messages()->list() — выборка сообщений
• messages()->edit() — редактирование
• messages()->delete() — удаление
• messages()->answerCallback() — callback answer

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() модули использовать нельзя.
• messages.getById() использует GET /messages с параметром message_ids.
• Для audio и video после успешной загрузки возможен временный attachment.not.ready.
• Для messages.answerCallback() в публичном schema pack уже есть подтверждённый success example.

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

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

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

Запуск unit tests:

vendor/bin/phpunit --configuration phpunit.xml

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

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