Download the PHP package mammothcoding/maxoxide without Composer

Readme in different languages: RU

maxoxide-php

A synchronous PHP library for building bots on the Max messenger platform. Inspired by the Rust library maxoxide.

Requires PHP 7.4+, the curl and json extensions. No third-party runtime dependencies. This PHP version is aligned with the Rust maxoxide 2.1.0 API surface: filtered polling, message markup parsing, new dialog updates, contact hash/max_info helpers, chat buttons, typed sender actions, media helpers, open_app/clipboard buttons, and image photos upload payloads.

Installation

Quick start

Project structure

API methods

userId vs chatId

These two identifiers are different:

• userId is the global ID of a MAX user.
• chatId is the ID of a concrete dialog, group, or channel.
• In a private chat, message->sender->userId identifies the user, while message->chatId() identifies the specific dialog with the bot.
• Use sendTextToChat / sendMessageToChat when you know the dialog or group chatId.
• Use sendTextToUser / sendMessageToUser when you only know the global userId.

User and ChatMember now expose MAX-style profile fields: firstName, lastName, username, description, avatarUrl, fullAvatarUrl, and commands where applicable. Use displayName() when you need one printable name. The legacy name alias remains available for existing PHP callers.

Dispatcher filters

The first matching handler wins. Register more specific filters earlier. Raw handlers always run before typed handlers. Unknown future update types are parsed as Update objects with raw() preserved.

Inline keyboard

Button::openAppFull($text, $webApp, $payload, $contactId) serializes the official MAX open_app wire model with web_app, optional payload, and optional contact_id. Button::chatFull($text, $chatTitle, $chatDescription, $startPayload, $uuid) serializes the documented chat button model. Current live testing still treats send-time chat button rejection as a MAX platform limitation when the API returns 400 Can't deserialize body.

File uploads

MAX uses a two-step upload flow. uploadFile and uploadBytes return a usable attachment token:

For the common upload-and-send flow, use the helpers:

Image uploads can return a MAX photos token map instead of a single token. The sendImage* helpers preserve that payload automatically and retry briefly while MAX reports the attachment as not processed yet.

Important: the photo type has been removed from the MAX API. Always use UploadType::IMAGE.

Webhook (without a framework)

Register the webhook once:

MAX requires HTTPS on port 443. Self-signed certificates are not supported.

Error handling

All API errors throw Maxoxide\MaxException:

Global handler for dispatcher callback errors:

Running tests

Known MAX platform gaps (May 2026)

• Button::requestContact is live-confirmed to deliver vcf_info, a valid hash, and max_info; vcf_phone may still be empty, so use phonesFromVcf() as a fallback.
• Button::requestGeoLocation is live-confirmed to deliver a structured location attachment with coordinates.
• Button::chatFull() follows the documented chat button JSON, but current live POST /messages requests may be rejected with 400 Can't deserialize body.
• setMyCommands currently returns 404 from POST /me/commands.

Live API test

There is an interactive harness for end-to-end checks against the real API:

At startup it asks for the language, update transport, bot token, and optional settings:

• update transport: long_polling or webhook
• bot URL for the tester
• webhook URL and secret for subscribe/unsubscribe checks, webhook mode, and restoring temporarily disabled subscriptions
• local webhook listen address when webhook transport is selected
• path to a local file for uploadFile
• optional paths to image, video, and audio files for media helper checks
• request delay, HTTP timeout, and polling timeout

Then the harness walks through each phase:

Private chat: sending /live to the bot activates the phase. It checks sendTextToChat, sendTextToUser, sendMarkdown*, message markup returned by getMessage, sendMessageToChatWithOptions, inline keyboards with callback/message/contact/location/link buttons, optional open_app, clipboard, opt-in chat button / message_chat_created, answerCallback, editMessage, getMessage, getMessages, getMessagesByIds, and deleteMessage.

Uploads: getUploadUrl for all types, uploadFile, uploadBytes, file helpers for chat/user, byte helpers, optional sendImageToChat, sendVideoToChat, getVideo, sendAudioToChat, and sending uploaded attachments back to the chat.

Updates transport: in long_polling mode the harness checks active webhook subscriptions, can temporarily unsubscribe them, restores them at the end, and probes getUpdatesWithTypes / getUpdatesRawWithTypes. In webhook mode it starts a local receiver and manual waits consume incoming webhook POSTs.

Webhook: getSubscriptions, subscribe, unsubscribe if a webhook URL is provided and the run is not already using webhook transport.

Commands: experimental setMyCommands check. MAX currently returns 404.

Group chat: sending /group_live in a group activates the phase. It checks getChat, getMembers, getMembersByIds, getAdmins, getMyMembership, typed sender actions, sender-action helpers, pin/unpin, editChat with automatic rollback, optional addAdmins/removeAdmin, addMembers, removeMember, opt-in removeMemberWithOptions(..., block=true), deleteChat, and leaveChat.

Optional dialog events: at the end the harness can wait for bot_stopped, dialog_cleared, dialog_muted, dialog_unmuted, and dialog_removed.

Each step is reported as PASS, FAIL, or SKIP, and the full summary is printed at the end.

License

MIT