Breaking backwards compatibility

This library is still under heavy development, so some changes will break backwards compatibility (BC). We try to keep breaking changes to a minimum, but also try to create the best solution for any given situation.

Here is a list of BC breaking changes in each version.

Unreleased

Return value of empty Entity properties

Entity properties that contain empty arrays now return an empty array instead of null.

Before:

// With no entities in the message.
$message->getEntities(); // null

After:

// With no entities in the message.
$message->getEntities(); // []

0.55.0

Move Animation out of Games namespace

The Animation entity has moved directly into the Entities namespace.

Before:

namespace Longman\TelegramBot\Entities\Games;

Now:

namespace Longman\TelegramBot\Entities;

0.54.0

Rename constants

The following constants have been renamed

• BASE_PATH -> TB_BASE_PATH
• BASE_COMMANDS_PATH -> TB_BASE_COMMANDS_PATH

0.50.0

Message::getCommand() return value

If message is not a command, null is returned instead of false.

Before:

// Text: "testing"
$message->getCommand(); // returns false

Now:

// Text: "testing"
$message->getCommand(); // returns null

0.48.0

Correct printError

ServerResponse->printError method now prints by default and returns by setting $return parameter, similar to print_r function.

Before:

$response->printError();     // returns error

Now:

$response->printError();     // prints error, returns true
$response->printError(true); // returns error

0.47.0

Private-only Admin Commands

Admin commands get the $private_only parameter set by default, making them work only in private chats. (#580)

If you have any admin command(s) that should be accessible in a public chat, you must manually add protected $private_only = false; to your command(s).

0.46.0

Request class refactor

Some Request:: methods that allow sending of files have been changed. As such, these methods no longer take an extra parameter that specifies the path to the file, but instead expect it to be part of the passed $data parameter.

Methods in question: sendPhoto, sendAudio, sendDocument, sendSticker, sendVideo, sendVoice, sendVideoNote.

Before:

$data = [
  'chat_id' => 123,
];
Request::sendPhoto($data, '/path/to/pic.jpg');

Now:

// For remote file paths.
$data = [
  'chat_id' => 123,
  'photo'   => 'https://example.com/path/to/pic.jpg',
];
Request::sendPhoto($data);

or

// For local file paths.
$data = [
  'chat_id' => 123,
  'photo'   => Request::encodeFile('/path/to/pic.jpg'),
];
Request::sendPhoto($data);

Request::setWebhook now without special handling!

Before:

Request::setWebhook($url, $data = []);

Now:

Request::setWebhook($data);

0.45.0

Remove deprecated methods

Before:

Telegram::getBotName();
Entity::getBotName();
Telegram::unsetWebhook();

Now:

Telegram::getBotUsername();
Entity::getBotUsername();
Telegram::deleteWebhook();

Chats params array

Request::sendToActiveChats and DB::selectChats now accept parameters as an options array and allow selecting of channels.

Before: Parameters to limit selection were all passed individually.

$results = DB::selectChats(
    true, // Select groups
    true, // Select supergroups
    true, // Select users
    null, // 'yyyy-mm-dd hh:mm:ss' date range from
    null, // 'yyyy-mm-dd hh:mm:ss' date range to
    null, // Specific chat_id to select
    null  // Text to search in user/group name
);

$results = Request::sendToActiveChats(
    'sendMessage',     // Callback function to execute (see Request.php methods)
    ['text' => $text], // Param to evaluate the request
    true,              // Send to groups
    true,              // Send to supergroups
    true,              // Send to users
);

Now: Parameters to limit selection now gets passed as an associative array.

$results = DB::selectChats([
    'groups'      => true,
    'supergroups' => true,
    'channels'    => true,
    'users'       => true,
    'date_from'   => null,
    'date_to'     => null,
    'chat_id'     => null,
    'text'        => null,
]);

$results = Request::sendToActiveChats(
    'sendMessage',     // Callback function to execute (see Request.php methods)
    ['text' => $text], // Param to evaluate the request
    [
        'groups'      => true,
        'supergroups' => true,
        'channels'    => false,
        'users'       => true,
    ]
);

Up-/Download directories

The upload and download directories are not set any more by default and must be set manually in the hook file.

$telegram->setUploadPath('/path/to/uploads');
$telegram->setDownloadPath('/path/to/downloads');

0.44.0

$update->getUpdateContent()

Before: Returned an array containing the update content.

$m   = $update->getUpdateContent();
$mid = $m['message']['message_id'];
$cid = $m['message']['chat']['id'];
$uid = $m['from']['id'];

Now: Correctly returns the Entity of the update content.

$m   = $update->getUpdateContent();
$mid = $m->getMessage()->getMessageId();
$cid = $m->getMessage()->getChat()->getId();
$uid = $m->getFrom()->getId();