max-bot-test/README.md

# max-bot-test

Тестовый бот, демонстрирующий весь публичный API библиотеки
[`pkirillw/max-bot-api-php`](https://github.com/pkirillw/max-bot-api-php.git).

Получает обновления через PSR-15 webhook (Slim 4 + Nyholm PSR-17), покрывает все 6
endpoint groups, 13 типов апдейтов, все типы кнопок и вложений. Запускается в Docker
Compose (php-fpm + nginx на `:8080`). Публичный HTTPS-адрес для webhook'а
подключаете своим туннелем (ngrok, cloudflared, обратный прокси и т.д.).

## Что внутри

- **6 endpoint groups**: `Bots`, `Chats`, `Messages`, `Uploads`, `Subscriptions`, `Debugs`.
- **13 типов апдейтов** — отдельный handler на каждый.
- **Все 7 типов inline-кнопок** (`callback`, `link`, `message`, `clipboard`,
  `request_contact`, `request_geo_location`, `open_app`) + все 3 `Intent`-окраса.
- **Все варианты загрузок**: file / URL / bytes / base64, отдельно для фото и media.
- **Все типы вложений**: photo / audio / video / file / location / contact / sticker.
- **Symfony Console CLI** для subscribe / unsubscribe / list / bot info / selftest.
- **PHPUnit**: unit-тесты на парсинг команд и клавиатуры, integration-тесты на
  webhook secret-check.

## Структура

```
src/
├── Bootstrap.php           — Slim + DI container + env loader
├── Handler/
│   ├── UpdateRouter.php    — dispatch UpdateInterface → handler
│   ├── AbstractUpdateHandler.php — общее логирование + error handling
│   └── Update/             — 13 handler'ов под каждый UpdateType
├── Scenario/               — обработчики команд (/help, /chats, /keyboard, …)
├── Command/                — bin/console команды
├── Keyboard/               — KeyboardFactory со всеми типами кнопок
├── Logger/                 — Monolog factory
└── Util/
    ├── CommandRouter.php   — command name → ScenarioInterface
    └── ParsedCommand.php   — парсер `/cmd arg1 arg2` и `/cmd:arg`
config/
├── container.php           — PHP-DI definitions
└── routes.php              — /webhook + /health
public/index.php            — Slim entrypoint
bin/console                 — CLI entrypoint
```

## Установка

```sh
git clone <this repo> max-bot-test
cd max-bot-test
cp .env.example .env
```

Заполните `.env`:

- `BOT_TOKEN` — токен бота из @MasterBot или панели MAX.
- `MAX_BOT_API_SECRET` — общий секрет для webhook. Сгенерируйте:
  `openssl rand -hex 32`.
- `WEBHOOK_URL` — публичный HTTPS-URL, по которому MAX будет присылать апдейты
  (например `https://bot.example.com/webhook`). Поднять публичный доступ можно
  любым способом: ngrok, cloudflared, Caddy/Nginx на VPS и т.п.
- `DEBUG_CHAT_ID`, `SELFTEST_CHAT_ID` — ID чата, в который бот может слать
  служебные сообщения (обычно ваш диалог с ботом).

Библиотека `pkirillw/max-bot-api-php` подключена через `repositories` в
`composer.json` как path-симлинк на `/var/www/max-php-client` внутри контейнера
(через volume `../max-php-client` в `docker-compose.yml`). Если библиотека лежит
в другом месте — поправьте volume и/или URL в `composer.json`.

## Запуск

```sh
make build       # собрать Docker-образы
make up          # запустить app + nginx (порт :8080)
make install     # composer install
```

Пробросьте свой публичный HTTPS на `localhost:8080` и впишите URL в `.env`:

```sh
WEBHOOK_URL=https://your-public-host/webhook
make up          # перезапустить чтобы подхватить новый env
make subscribe   # эквивалент: docker compose exec app bin/console webhook:subscribe
```

Готово. Откройте диалог с ботом в MAX, отправьте `/help`.

## Команды бота

Полный список — в `/help` (или в `src/Scenario/HelpScenario.php`). Кратко:

**Bot**: `/bot`, `/bot_patch <name>`.
**Chats**: `/chats`, `/chat <id>`, `/members <id>`, `/admins <id>`,
`/action <id> <typing_on|typing_off|mark_seen|sending_photo|sending_video|sending_audio>`,
`/pin <id> <mid>`, `/edit_chat <id> <title>`, `/add_member <id> <userId>`,
`/remove_member <id> <userId>`, `/leave <id>`.
**Messages**: `/send_text <text>`, `/send_markdown <text>`, `/send_html <text>`,
`/reply <mid> <text>`, `/forward <mid>`, `/edit <mid> <text>`, `/delete <mid>`,
`/messages <id> [count]`, `/message <mid>`, `/markup <userId>`, `/notify <text>`,
`/disable_preview <url>`, `/keyboard`.
**Uploads**: `/upload_photo_file [path]`, `/upload_photo_url <url>`,
`/upload_photo_bytes`, `/upload_photo_base64`, `/upload_audio [path]`,
`/upload_video [path]`, `/upload_file [path]`,
`/upload_url <audio|video|file> <url>`.
**Attachments**: `/attach_location <lat> <lng>`, `/attach_contact <name> <id>`,
`/attach_sticker <code>`.
**Phone**: `/phone_check <phone>`, `/phone_list <phone1,phone2>`.
**Debug**: `/debug <on|off|raw|err|status>`.

## CLI

```sh
bin/console webhook:subscribe [--url=…] [--secret=…] [--types=msg_created,…]
bin/console webhook:unsubscribe [url]
bin/console subs:list
bin/console bot:info
bin/console selftest        # дымовой тур по всем endpoint groups
```

## Тесты

```sh
make test
# или локально:
vendor/bin/phpunit
```

## Логи

```
storage/logs/app.log
make logs           # app + nginx в реальном времени
```

## Известные особенности

- **Long polling не поддерживается** библиотекой. Получение событий — только
  webhook. Запуск без публичного URL невозможен (используйте cloudflared).
- `DebugScenario::off` не может выключить debug-чат в рантайме — `Debugs` не
  выставляет chatId обратно в null. Перезапустите контейнер без `DEBUG_CHAT_ID`.
- При `attachment.not.ready` библиотека сама делает до 3 retries с
  экспоненциальной задержкой — повторных попыток на уровне бота не требуется.

## Лицензия

Apache-2.0 — как и сама библиотека.