telegram-bot-php/core

A PHP library that makes using Telegram Bot API much easier.

v1.1.0 2024-06-24 05:51 UTC

Requires

• php: >=8.2
• ext-curl: *
• ext-json: *
• ext-mbstring: *
• guzzlehttp/guzzle: ^7.8
• symfony/dotenv: ^v7.1

Requires (Dev)

• fakerphp/faker: ^1.23
• phpunit/phpunit: ^11.2
• psr/log: ^1.1|^2.0|^3.0

MIT

• Shahrad Elahi
• LiteHex

• php
• library
• bot
• core
• telegram
• update-handler

README

Telegram Bot PHP

This library is a simple and easy to use library for creating Telegram API Bots, and this library is designed to provide a platform where one can simply write a bot and have interactions in a matter of minutes.

Table of Contents

• Introduction
  • Installation
  • Getting started
• Webhook
  • Use self-signed certificate
  • Delete webhook
• Update Handling
  • Anonymous plugins and handlers
  • Create a handler for updates
  • Filter incoming updates
• Plugins
  • Create plugin for Handler class
  • Available events and methods
• Supports
• Logging
• Error Handling
• Example bot
• Troubleshooting
• Code of Conduct
• Contributing
• License

Introduction

This is an official announcement of support, which allows integrators of all sorts to bring automated interactions with the Telegram Bot API to their users.

This library features:

• The easiest and simplest way for update handling
• Support for all types and methods according to Telegram Bot API 6.0
• Handling WebAppData and data encryption/validation
• Crash handling and error reporting
• The ability to create advanced Plugins with their asynchronous methods
• The ability to manage Channels from the bot admin interface
• Downloading and uploading large files
• Full support for inline bots
• Inline keyboard support
• And many more...

Installation

composer require telegram-bot-php/core

Click for help with installation

Install Composer

If the above step didn't work, install composer and try again.

Debian / Ubuntu

sudo apt-get install curl php-curl
curl -s https://getcomposer.org/installer | php
php composer.phar install

Composer not found? Use this command instead:

php composer.phar require "telegram-bot-php/core"

Windows:

Download installer for Windows

Getting started

<?php
require __DIR__ . '/vendor/autoload.php';

$admin_id = 123456789;
$bot_token = 'your_bot_token';

\TelegramBot\Telegram::setToken($bot_token);
\TelegramBot\CrashPad::setDebugMode($admin_id);

$result = \TelegramBot\Request::sendMessage([
   'chat_id' => $admin_id,
   'text' => 'text',
]);

echo $result->getRawData(false); // {"ok": true, "result": {...}}

Webhook

Create set-hook.php with the following contents:

<?php
require __DIR__ . '/vendor/autoload.php';

\TelegramBot\Telegram::setToken($bot_token);
$response = \TelegramBot\Request::setWebhook([
   'url' => 'https://your-domain.com/webhook/' . $bot_token,
]);

if ($response->isOk()) {
   echo $response->getDescription();
   exit(0);
}

Use self-signed certificate

\TelegramBot\Request::setWebhook([
   'url' => 'https://your-domain.com/webhook/' . $bot_token,
   'certificate' => 'path/to/certificate.pem',
]);

Delete webhook

\TelegramBot\Request::deleteWebhook();

Update Handling

Create a handler for updates

<?php

use TelegramBot\Entities\Update;
use TelegramBotTest\EchoBot\Plugins\MainPlugin;

class Handler extends \TelegramBot\UpdateHandler {

   public function __process(Update $update): void {
      self::addPlugins([
         MainPlugin::class,
      ]);
   }

}

Filter incoming updates

Filtering incoming updates by their type is easy.

$updateHandler->filterIncomingUpdates([
   Update::TYPE_MESSAGE,
   Update::TYPE_CALLBACK_QUERY,
]);

Or just go advanced:

$updateHandler->filterIncomingUpdates([
   Update::TYPE_MESSAGE => function (\TelegramBot\Entities\Update $update) {
      return $update->getMessage()->getChat()->getId() === 259760855;
   }
]);

Plugins

The Plugins are a way to create a bot that can do more than just echo back the message.

Create plugin for Handler class

<?php

use TelegramBot\Entities\Message;
use TelegramBot\Entities\WebAppData;

class MainPlugin extends \TelegramBot\Plugin {

   public function onMessage(int $update_id, Message $message): \Generator {
      if ($message->getText() === '/start') {
         yield \TelegramBot\Request::sendMessage([
            'chat_id' => $message->getChat()->getId(),
            'text' => 'Hello, ' . $message->getFrom()->getFirstName(),
         ]);
      }

      if ($message->getText() === '/ping') {
         yield \TelegramBot\Request::sendMessage([
            'chat_id' => $message->getChat()->getId(),
            'text' => 'pong',
         ]);
      }
   }

   public function onWebAppData(int $update_id, WebAppData $webAppData): \Generator {
      yield \TelegramBot\Request::sendMessage([
         'chat_id' => $webAppData->getUser()->getId(),
         'text' => 'Hello, ' . $webAppData->getUser()->getFirstName(),
      ]);
   }

}

Anonymous plugins and handlers

$commands = new class() extends \TelegramBot\Plugin {

   public function onUpdate(\TelegramBot\Entities\Update $update): \Generator {
      // Write your code here
   }

};

$admin = new class() extends \TelegramBot\Plugin {

   // TODO: Write your code here

};

(new \TelegramBot\UpdateHandler())->addPlugins([$commands, $admin])->resolve();

Available events and methods

class SomePlugin extends \TelegramBot\Plugin {

   public function onUpdate(Update $update): \Generator {}

   public function onMessage(int $update_id, Message $message): \Generator {}

   public function onEditedMessage(int $update_id, EditedMessage $editedMessage): \Generator {}

   public function onChannelPost(int $update_id, ChannelPost $channelPost): \Generator {}

   public function onEditedChannelPost(int $update_id, EditedChannelPost $editedChannelPost): \Generator {}

   public function onInlineQuery(int $update_id, InlineQuery $inlineQuery): \Generator {}

   public function onChosenInlineResult(int $update_id, ChosenInlineResult $chosenInlineResult): \Generator {}

   public function onCallbackQuery(int $update_id, CallbackQuery $callbackQuery): \Generator {}

   public function onShippingQuery(int $update_id, ShippingQuery $shippingQuery): \Generator {}

   public function onPreCheckoutQuery(int $update_id, PreCheckoutQuery $preCheckoutQuery): \Generator {}

   public function onPoll(int $update_id, Poll $poll): \Generator {}

   public function onPollAnswer(int $update_id, PollAnswer $pollAnswer): \Generator {}

   public function onWebAppData(int $update_id, WebAppData $webAppData): \Generator {}

}

Supports

This library supports evey Telegram Bot API method and entity since API version 6.0.

Error Handling

Using CrashPad for reporting error through telegram. just add below to your Update handler.

\TelegramBot\CrashPad::setDebugMode(259760855);

Troubleshooting

Please report any bugs you find on the issues page.

Code of Conduct

The Telegram-Bot-PHP Code of Conduct can be found at this document.

Contributing

Thank you for considering contributing to this project. please open an issue or pull request if you have any suggestions or just email [e-mail].

License

The Telegram-Bot-PHP library is open-sourced under the MIT license.