v2.0.0

EN

Release summary

This release updates maxoxide-php for the current public MAX REST API, adds convenience helpers for media sending, makes update parsing more forward-compatible, and expands the dispatcher into a more practical routing layer.

Breaking changes

• Update::$timestamp is now nullable because unknown future updates may omit a timestamp.
• Use Update::timestampOrDefault() when the previous 0 fallback behavior is desired.
• Plain text should be represented by leaving NewMessageBody::$format unset. MessageFormat now exposes only documented MAX format values: MARKDOWN and HTML.
• Code that constructs raw Button objects for open_app should migrate to Button::openApp(), Button::openAppWithPayload(), or Button::openAppFull(), which serialize the official MAX wire model with web_app, optional payload, and optional contact_id.

User::$name and ChatMember::$name remain available as legacy aliases in PHP, but new code should prefer firstName, lastName, and displayName().

Added

• Added typed fallback support for unknown Update and unknown attachments, preserving raw JSON for later inspection.
• Added attachment deserialization for both wrapped payload objects and flat attachment objects, so Button::requestGeoLocation() updates can deserialize as AttachmentKind::LOCATION with latitude and longitude.
• Added typed string value classes:
  • ChatType
  • ChatStatus
  • MessageFormat
  • ButtonIntent
  • LinkType
  • AttachmentKind
  • ChatAdminPermission
  • SenderAction
• Added more complete MAX models for users, chats, members, admins, video metadata, image/photo payloads, upload endpoints, upload responses, and webhook subscriptions.
• Added current MAX profile fields to User and ChatMember:
  • firstName
  • lastName
  • username
  • description
  • avatarUrl
  • fullAvatarUrl
  • commands, where available
• Added Button::openApp(), Button::openAppWithPayload(), and Button::openAppFull() using the official web_app, payload, and contact_id fields.
• Added Button::clipboard().
• Added builders and helpers for outgoing messages and attachments:
  • NewMessageBody::empty()
  • NewMessageBody::textOpt()
  • NewMessageBody::withAttachments()
  • NewMessageBody::withReplyTo()
  • NewMessageBody::withForwardFrom()
  • NewMessageBody::withNotify()
  • NewAttachment::imageUrl()
  • NewAttachment::imagePhotos()
  • NewAttachment::imagePayload()
• Added SendMessageOptions with disable_link_preview.
• Added message, video, member, and admin endpoints:
  • sendMessageToChatWithOptions()
  • sendMessageToUserWithOptions()
  • getMessagesByIds()
  • getVideo()
  • getMembersByIds()
  • addAdmins()
  • removeAdmin()
• Added typed sender action methods:
  • sendSenderAction()
  • sendTypingOn()
  • sendSendingImage()
  • sendSendingVideo()
  • sendSendingAudio()
  • sendSendingFile()
  • markSeen()
• Added upload-and-send helpers for both chat and user recipients:
  • sendImageToChat() / sendImageToUser()
  • sendVideoToChat() / sendVideoToUser()
  • sendAudioToChat() / sendAudioToUser()
  • sendFileToChat() / sendFileToUser()
  • byte-based variants for the same media types
• Added Bot::getUpdatesRaw() and RawUpdatesResponse for raw polling before typed parsing.
• Added Dispatcher::onUpdate(), composable Filter values, regex text filters, media/file attachment filters, onStart(), task(), onRawUpdate(), and raw dispatch via dispatchRaw().
• Added examples/media_bot.php and examples/dispatcher_filters_bot.php.

Changed

• getUploadUrl() now returns an UploadEndpoint object and serializes upload types using documented lowercase wire values.
• Long polling now receives raw update JSON first, then dispatches through raw and typed handlers.
• Webhook handling now dispatches raw JSON through the same dispatcher path as long polling.
• Upload helpers now accept attachment tokens from either the upload endpoint response or multipart upload response, preserve the MAX photos token map for image send helpers, and retry briefly while MAX reports an uploaded attachment as not processed yet.
• uploadFile() and uploadBytes() still return a simple token string for existing callers, but image uploads can now also be represented as ImageAttachmentPayload when using send helpers.
• README examples now use the newer builders, dispatcher filters, typed sender actions, and media helpers.
• examples/live_api_test.php now covers the expanded PHP API, including raw updates, message options, media helpers, getVideo(), member/admin helpers, typed sender actions, open_app, and clipboard.

Fixed

• Fixed Composer autoloading for aggregate source files such as src/Types.php and src/Dispatcher.php, so vendor/autoload.php now loads classes like Maxoxide\User, Maxoxide\Update, and Maxoxide\Filter without requiring bootstrap.php.
• bootstrap.php now uses require_once, so it remains compatible with Composer autoload and older direct source-tree workflows.
• Unknown or malformed attachments no longer break entire message/update parsing.
• Request-location payloads can now be parsed when MAX sends a flat attachment object.

MAX platform gaps documented by live testing

• Button::requestContact() sends successfully, but incoming contact attachments may contain empty contact_id and vcf_phone.
• Button::requestGeoLocation() may arrive either as a structured location attachment or as a client map-card/link fallback.
• sendSenderAction($chatId, SenderAction::TYPING_ON) returns success from the API, but the visible typing indicator is not reliably confirmed in the client.
• setMyCommands() remains experimental: live POST /me/commands requests return 404, and the public MAX REST docs do not currently expose a documented write endpoint for command menu updates.

Verification

• composer dump-autoload
• php -r 'require "vendor/autoload.php"; var_dump(class_exists("Maxoxide\\User"), class_exists("Maxoxide\\Update"), class_exists("Maxoxide\\Filter"));'
• find src tests examples -name '*.php' -exec php -l {} \;
• vendor/bin/phpunit tests
• vendor/bin/phpunit --bootstrap bootstrap.php tests

RU

Кратко о релизе

Этот релиз обновляет maxoxide-php под текущий публичный REST API MAX, добавляет вспомогательные методы для отправки медиа, делает разбор обновлений устойчивее к будущим типам MAX и расширяет Dispatcher до более практичного роутинга.

Ломающие изменения

• Update::$timestamp теперь nullable, потому что неизвестные будущие update могут не содержать timestamp.
• Для старого поведения с резервным значением 0 используйте Update::timestampOrDefault().
• Обычный текст должен задаваться отсутствием NewMessageBody::$format. MessageFormat теперь содержит только документированные MAX-значения: MARKDOWN и HTML.
• Код, который вручную собирал сырые Button-объекты для open_app, стоит перевести на Button::openApp(), Button::openAppWithPayload() или Button::openAppFull(): они сериализуют официальную MAX wire-модель с web_app, опциональным payload и опциональным contact_id.

User::$name и ChatMember::$name в PHP оставлены как legacy aliases, но новый код лучше писать через firstName, lastName и displayName().

Добавлено

• Добавлен резервный разбор неизвестных Update и неизвестных вложений с сохранением raw JSON.
• Добавлен разбор вложений как в форме с обёрнутым payload, так и в плоской форме объекта вложения, поэтому updates от Button::requestGeoLocation() могут десериализоваться как AttachmentKind::LOCATION с latitude и longitude.
• Добавлены типизированные классы строковых значений:
  • ChatType
  • ChatStatus
  • MessageFormat
  • ButtonIntent
  • LinkType
  • AttachmentKind
  • ChatAdminPermission
  • SenderAction
• Расширены модели MAX для пользователей, чатов, участников, администраторов, video metadata, image/photo payloads, upload endpoints, upload responses и webhook subscriptions.
• В User и ChatMember добавлены актуальные поля профиля MAX:
  • firstName
  • lastName
  • username
  • description
  • avatarUrl
  • fullAvatarUrl
  • commands, где они доступны
• Добавлены Button::openApp(), Button::openAppWithPayload() и Button::openAppFull() с официальными полями web_app, payload, contact_id.
• Добавлен Button::clipboard().
• Добавлены builders и вспомогательные методы для исходящих сообщений и вложений:
  • NewMessageBody::empty()
  • NewMessageBody::textOpt()
  • NewMessageBody::withAttachments()
  • NewMessageBody::withReplyTo()
  • NewMessageBody::withForwardFrom()
  • NewMessageBody::withNotify()
  • NewAttachment::imageUrl()
  • NewAttachment::imagePhotos()
  • NewAttachment::imagePayload()
• Добавлен SendMessageOptions с disable_link_preview.
• Добавлены методы для сообщений, видео, участников и администраторов:
  • sendMessageToChatWithOptions()
  • sendMessageToUserWithOptions()
  • getMessagesByIds()
  • getVideo()
  • getMembersByIds()
  • addAdmins()
  • removeAdmin()
• Добавлены типизированные действия отправителя:
  • sendSenderAction()
  • sendTypingOn()
  • sendSendingImage()
  • sendSendingVideo()
  • sendSendingAudio()
  • sendSendingFile()
  • markSeen()
• Добавлены helpers загрузки и отправки для chat/user адресатов:
  • sendImageToChat() / sendImageToUser()
  • sendVideoToChat() / sendVideoToUser()
  • sendAudioToChat() / sendAudioToUser()
  • sendFileToChat() / sendFileToUser()
  • варианты для байтов тех же типов медиа
• Добавлены Bot::getUpdatesRaw() и RawUpdatesResponse для raw polling до...

v1.0.0

First stable release.