PHPackages geekcodev/laravel-max-client - 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. [HTTP & Networking](/categories/http) 4. / 5. geekcodev/laravel-max-client ActiveLibrary[HTTP & Networking](/categories/http) geekcodev/laravel-max-client ============================ Laravel adapter for the MAX Messenger Bot API client (geekcodev/max-php-client) v1.0.0(today)01↑2900%MITPHPPHP ^8.4CI passing Since Aug 8Pushed todayCompare [ Source](https://github.com/geekcodev/laravel-max-client)[ Packagist](https://packagist.org/packages/geekcodev/laravel-max-client)[ Docs](https://github.com/geekcodev/laravel-max-client)[ RSS](/packages/geekcodev-laravel-max-client/feed)WikiDiscussions main Synced today READMEChangelog (1)Dependencies (10)Versions (3)Used By (0) geekcodev/laravel-max-client ============================ [](#geekcodevlaravel-max-client) Тонкий Laravel-адаптер для **MAX Messenger Bot API** поверх framework-agnostic ядра [`geekcodev/max-php-client`](https://github.com/geekcodev/max-php-client). Пакет отвечает только за «Laravel-клей»: конфиг, DI, фасад, вебхук-роутинг, очередь. Вся бизнес-логика API (DTO, эндпоинты, ретраи, rate limit, безопасность, загрузка медиа) живёт в ядре — см. его документацию и OpenAPI-спецификацию `max-openapi`. Требования ---------- [](#требования) - PHP ^8.4 - Laravel ^12.0|^13.0 - `geekcodev/max-php-client` ^1.0 Установка --------- [](#установка) ``` composer require geekcodev/laravel-max-client ``` Сервис-провайдер `GeekCo\LaravelMaxClient\MaxServiceProvider` и alias `Max`подхватываются автоматически (package discovery). Затем опубликуйте конфиг: ``` php artisan vendor:publish --tag=laravel-max-client-config ``` Конфигурация ------------ [](#конфигурация) Минимально необходима одна переменная — токен бота: ``` MAX_API_TOKEN=your-bot-access-token ``` Все доступные переменные (имена см. в `.env.example`): ПеременнаяПо умолчаниюОписание`MAX_API_TOKEN`—Токен бота (заголовок `Authorization`)`MAX_BASE_URI``https://platform-api2.max.ru`Базовый URI API (домен `platform-api2`)`MAX_WEBHOOK_ENABLED``false`Регистрировать вебхук-роут`MAX_WEBHOOK_SECRET`—Секрет вебхука (без него роут не включается)`MAX_WEBHOOK_QUEUE``default`Очередь для джобов обработки Update`MAX_WEBHOOK_PATH``/max/webhook`Путь вебхук-роута`MAX_RETRY_*`3 / 1 / 30 / 2 / falseРетраи (попытки/базовая/макс. задержка/фактор/не-идемпотентные)`MAX_RATE_LIMIT_*`2.0 / 2.0Token bucket: токенов в секунду / максимум> Токен и секрет никогда не должны попадать в код, логи или коммиты — только env. Использование ------------- [](#использование) Фасад `Max` резолвит единый экземпляр `ApiClient` из контейнера: ``` use GeekCo\LaravelMaxClient\Facades\Max; use GeekCo\MaxPhpClient\Dto\Recipient; use GeekCo\MaxPhpClient\Dto\NewMessageBody; $me = Max::getMe(); Max::sendMessage( new Recipient(chatId: $chatId), new NewMessageBody(text: 'Привет!'), ); ``` Список доступных методов — в ядре `GeekCo\MaxPhpClient\ApiClient`. Полные рабочие примеры — в каталоге [`examples/`](examples/): `basic-usage.php` (фасад), `webhook-listener.php` (обработка апдейтов), `custom-http-client.php` (подмена PSR-18 клиента), `long-polling-local-dev.md` (настройка и запуск Long Polling локально и в Docker). ### Свой PSR-18 клиент [](#свой-psr-18-клиент) По умолчанию используется Guzzle с опциями `http.options`. Чтобы подменить транспорт, зарегистрируйте свою реализацию `Psr\Http\Client\ClientInterface` в контейнере: ``` // AppServiceProvider $this->app->instance(\Psr\Http\Client\ClientInterface::class, $yourClient); ``` Вебхук ------ [](#вебхук) 1. Включите вебхук и задайте секрет: ``` MAX_WEBHOOK_ENABLED=true MAX_WEBHOOK_SECRET=some-secret ``` Роут `POST /max/webhook` (имя `max.webhook`) регистрируется **только** при включённом флаге и заданном секрете (fail-closed). Роут вне CSRF, с `throttle:60,1`(настраивается в `webhook.middleware` конфига). Приёмка проверяет `X-Max-Bot-Api-Secret` через `hash_equals` (иначе 401). 2. Подпишитесь на событие доставки `MaxUpdateReceived`: ``` // app/Providers/EventServiceProvider.php protected $listen = [ \GeekCo\LaravelMaxClient\Webhook\MaxUpdateReceived::class => [ YourUpdateListener::class, ], ]; ``` Обработчик: ``` use GeekCo\LaravelMaxClient\Webhook\MaxUpdateReceived; class YourUpdateListener { public function handle(MaxUpdateReceived $event): void { $update = $event->update; // GeekCo\MaxPhpClient\Dto\Update // бизнес-обработка апдейта } } ``` 3. Пакет ставит `HandleMaxUpdateJob` в очередь `webhook.queue` на **каждый** `Update`и сразу отвечает `200` (API требует ответ в течение 30 секунд). Если на событие нет слушателей — работа в очередь не ставится. Long Polling (локальная разработка) ----------------------------------- [](#long-polling-локальная-разработка) Вебхук требует публичного домена с HTTPS и доверенным CA, поэтому для локальной разработки используйте Long Polling: ``` php artisan max:listen ``` Команда опрашивает `GET /updates` через ядро (`LongPollingRunner`) и ставит `HandleMaxUpdateJob` в ту же очередь (`webhook.queue`) — апдейты обрабатывает тот же слушатель `MaxUpdateReceived`. Остановка — Ctrl+C. Опции: - `--marker=42` — начать с указанного marker (последний обработанный timestamp); - `--once` — обработать одну партию апдейтов и завершиться (для cron/смоука). Поведение по умолчанию — в секции `long_polling` конфига (env `MAX_POLLING_*`): `limit` (100), `timeout` (30 сек), `break_on_failure` (`true` — завершаться при ошибке API; для долгой работы в dev задайте `MAX_POLLING_BREAK_ON_FAILURE=false`). > Активная webhook-подписка отключает Long Polling — не используйте оба механизма одновременно. Тестирование ------------ [](#тестирование) ``` # unit-тесты (Testbench), lint, статика, покрытие, аудит composer run lint composer run format composer run analyse vendor/bin/phpunit composer run coverage composer audit ``` Интеграционные смоук-тесты против реального API (read-only, нужен `MAX_API_TOKEN`, TLS из Docker-сети блокируется — только `--network host`): ``` source .env && docker run --rm --network host \ -v "$(pwd)":/var/www/html -w /var/www/html \ -e MAX_API_TOKEN="$MAX_API_TOKEN" \ ghcr.io/geekcodev/php:8.4-bookworm vendor/bin/phpunit --group integration ``` Лицензия -------- [](#лицензия) MIT (c) 2026 Evgeny Semenov. См. `LICENSE`. ### Health Score 42 — FairBetter than 88% of packages Maintenance100 Actively maintained with recent releases Popularity2 Limited adoption so far Community6 Small or concentrated contributor base Maturity52 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 Unknown Total 1 Last Release 0d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/2421ba0622fad89e516855478d693dd25c853898c58414ce5633116901bf2323?d=identicon)[Evgeny Semenov](/maintainers/Evgeny%20Semenov) --- Top Contributors [![geekcodev](https://avatars.githubusercontent.com/u/245257060?v=4)](https://github.com/geekcodev "geekcodev (3 commits)") --- Tags apiclientlaravelpsr-18queuewebhookbotMessengermax ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/geekcodev-laravel-max-client/health.svg) ``` [![Health](https://phpackages.com/badges/geekcodev-laravel-max-client/health.svg)](https://phpackages.com/packages/geekcodev-laravel-max-client) ``` ### Alternatives [tempest/framework The PHP framework that gets out of your way. 2.3k37.6k19](/packages/tempest-framework)[bushlanov-dev/max-bot-api-client-php Max Bot API Client library 488.7k](/packages/bushlanov-dev-max-bot-api-client-php)[typo3/cms TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL. 1.2k1.9M122](/packages/typo3-cms)[flow-php/flow PHP ETL - Extract Transform Load - Data processing framework 86337.5k](/packages/flow-php-flow)[neuron-core/neuron-ai The PHP Agentic Framework. 2.0k832.6k52](/packages/neuron-core-neuron-ai)[telnyx/telnyx-php Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network. 36826.2k2](/packages/telnyx-telnyx-php) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)