README

maxoxide-php

Production-oriented synchronous PHP SDK for the MAX messenger Bot API.

Russian README | English guides | Russian guides | API support | v3 migration

Install

composer require mammothcoding/maxoxide:^3.0

Requires PHP 7.4+, ext-curl, and ext-json. The package has no third-party runtime dependencies.

Quick start

<?php

require 'vendor/autoload.php';

use Maxoxide\Bot;
use Maxoxide\Context;
use Maxoxide\Dispatcher;

$dispatcher = new Dispatcher(Bot::fromEnv()); // MAX_BOT_TOKEN
$dispatcher->onMessage(static function (Context $context): void {
    $message = $context->update->message;
    if ($message !== null) {
        $context->bot->sendTextToChat(
            $message->chatId(),
            $message->text() ?? '(no text)'
        );
    }
});
$dispatcher->startPolling();

MAX_BOT_TOKEN=... php examples/echo_bot.php

MAX recommends HTTPS webhooks for production. Long polling is intended for development and testing.

Highlights

Typed messages, chats, members, callbacks, constructed-message events, comments, subscriptions, and uploads.
Structured exceptions with HTTP status, MAX code, bounded raw diagnostics, and Retry-After support.
Secure builder with deterministic CA trust, timeouts, HTTP/SOCKS proxy, retries, local rate limits, and safe custom endpoints.
File-backed multipart and resumable Content-Range uploads with active-chunk retry, progress, and cancellation.
Exact command parsing, composable filters, middleware, class-keyed state, scheduled tasks, and cooperative shutdown.
Bounded plain-PHP webhook receiver with constant-time secret verification.
Mini App HMAC/freshness validation and requestContact() signature verification.
Experimental Digital ID partner client isolated from the bot token and Bot API client.
Unknown update and attachment data preservation where MAX can extend its wire format.

Guides

Topic	English	Russian
Getting started and IDs	Guide	Руководство
Client, TLS, proxy, retry, limits	Guide	Руководство
Messages, formatting, attachments, uploads	Guide	Руководство
Dispatcher, middleware, state, shutdown	Guide	Руководство
Webhooks	Guide	Руководство
Mini Apps	Guide	Руководство
Digital ID	Guide	Руководство
Live API validation	Guide	Руководство
Production	Guide	Руководство
Recipes	Index	Список

Examples

Basics: echo_bot.php, keyboard_bot.php.
Dispatcher: dispatcher_filters_bot.php.
Messages and uploads: media_bot.php, resumable_upload.php.
Network and webhooks: client_configuration.php, webhook_bot.php.
Platform integrations: miniapp_validation.php, digital_id.php.
Advanced integration: live_api_test.php.

Run an example after installing dependencies:

php examples/<name>.php

live_api_test.php lets library users validate real Bot API behavior with their own dedicated test bot, controlled users, chats, and credentials. Run it from a source checkout matching your installed version and review its real side effects first; see the live API validation guide.

Important constraints

Use chatId for a concrete dialog/group/channel and userId for a global MAX user.
Never send a bot token in a query parameter. maxoxide-php uses the Authorization header.
Do not disable TLS verification. The managed client includes the required Russian trust root.
Comments are typed, but MAX currently marks all five methods temporarily unavailable.
Digital ID is an experimental partner integration without live-service verification. Validate its endpoint, authorization, and caller-owned models against current onboarding documentation before production use.

Read SECURITY.md, API_SUPPORT.md, and CHANGELOG.md before production deployment.

License

MIT

mammothcoding / maxoxide

Maintainers

Package info

Statistics

Security