diff --git a/README.md b/README.md index bc33496..0296955 100644 --- a/README.md +++ b/README.md @@ -12,17 +12,7 @@ native around the API. * [TgBotLib](#tgbotlib) * [Table of contents](#table-of-contents) * [Versioning](#versioning) - * [Installation](#installation) - * [Compile from source](#compile-from-source) - * [Requirements](#requirements) - * [Usage](#usage) - * [Documentation](#documentation) - * [Single-Threaded & Multi-Threaded Bots](#single-threaded--multi-threaded-bots) - * [Single-Threaded Bots](#single-threaded-bots) - * [Multi-Threaded Bots](#multi-threaded-bots) - * [Commands & Event Handlers](#commands--event-handlers) - * [Commands](#commands) - * [Event Handlers](#event-handlers) + * [TODO](#todo) * [License](#license) @@ -36,274 +26,9 @@ version is `4`. Library patches are used to fix bugs or add improvements in the Telegram Bot API version. -## Installation +## TODO -The library can be installed using ncc: - -```bash -ncc package install -p "nosial/libs.tgbot=latest@n64" -``` - -or by adding the following to your project.json file under the `build.dependencies` section: -```json -{ - "name": "net.nosial.tgbotlib", - "version": "latest", - "source_type": "remote", - "source": "nosial/libs.tgbot=latest@n64" -} -``` - -If you don't have the n64 source configured, you can add it by running the following command: -```bash -ncc source add --name n64 --type gitlab --host git.n64.cc -``` - - -If you don't have ncc installed, you can refer to the [ncc documentation](https://git.n64.cc/nosial/ncc) for more -information on how to install it. See [Building NCC from source](https://git.n64.cc/nosial/ncc/-/blob/master/DOCUMENTATION.md#building-ncc-from-source) -and [Installing NCC](https://git.n64.cc/nosial/ncc/-/blob/master/DOCUMENTATION.md#installing-ncc) for more information. - - -## Compile from source - -To compile the library from source, you need to have [ncc](https://git.n64.cc/nosial/ncc) installed, then run the -following command: - -```bash -ncc build -``` - - -## Requirements - -The library requires PHP 8.0 or higher. - - -## Usage - - 1. Import the library using `import('net.nosial.tgbotlib');` - 2. Create a new instance of the `TgBotLib\Bot` class, passing the bot token as the first argument - 3. Profit - -```php -require 'ncc'; -import('net.nosial.tgbotlib'); - -$bot = new TgBotLib\BotOld(''); - -/** @var \TgBotLib\Objects\Update $update */ -foreach ($bot->getUpdates() as $update) -{ - $bot->sendMessage($update->getMessage()->getChat()->getId(), 'Hello World!'); -} -``` - -Each method of the `TgBotLib\Bot` class is named after the corresponding method of the Telegram Bot API, all methods -contains an optional `$parameters` argument that can be used to pass additional parameters to the API method. - -But for methods that has required parameters, the library provides a more convenient way to pass them, by using -named parameters. For example, the `sendMessage` method requires the `chat_id` and `text` parameters, but instead -of passing them as an array, you can pass them as named parameters: - -```php -$bot->sendMessage( - chat_id: '', - text: 'Hello World!', - options: [ - 'parse_mode' => 'Markdown', - 'disable_web_page_preview' => true, - ] -); -``` - -## Documentation - -Almost everything in the library has PhpDoc documentation, so you can use your IDE to get documentation for the -library. For example, in PhpStorm, you can press `Ctrl+Q` on a method to get the documentation for it: - -![PhpStorm Documentation](assets/documentation.png) - -## Single-Threaded & Multi-Threaded Bots - -This part will explain how to implement single-threaded and multi-threaded bots using the library. -For more examples see the [tests](tests) directory. - -### Single-Threaded Bots - -To implement a single-threaded bot, it's very self-explanatory, you just need to create a new instance of the -`TgBotLib\Bot` class and use it to handle the updates: - -```php -getUpdates() as $update) - { - $bot->sendMessage($update->getMessage()->getChat()->getId(), 'Hello World!'); - } - } -``` - -This approach is very simple and allows for easier debugging, but it's not recommended for production use, because -it will block the script until the updates are handled, and if the bot receives a lot of updates, it will take a -long time to handle them. So it's recommended to use a multithreaded approach for production bots. - - -### Multi-Threaded Bots - -To implement a multi-threaded bot, you need to install [TamerLib](https://git.n64.cc/nosial/libs/tamer) which will allow -you to run parallel operations using a Message Server - -First create a worker process that will handle the updates: - -```php -'); - - // Setup command handlers - $bot->setCommandHandler('start', new \commands\StartCommand()); - $bot->setCommandHandler('hash', new \commands\HashCommand()); - - // Run TamerLib forever. - \TamerLib\tm::initialize(\TamerLib\Enums\TamerMode::WORKER); - \TamerLib\tm::addFunction('handle_update', [$bot, 'handleUpdate']); - \TamerLib\tm::run(); -``` - -Then create a master process that will send the updates to the worker: - -```php -'); - \TamerLib\tm::initialize(\TamerLib\Enums\TamerMode::CLIENT); - \TamerLib\tm::createWorker(8, __DIR__ . DIRECTORY_SEPARATOR . 'worker.php'); - - // Handle updates forever - while(true) - { - // Get updates, push the update object to the worker - foreach ($bot->getUpdates() as $update) - { - \TamerLib\tm::dof('handle_update', [$update]); - } - - \TamerLib\tm::wait(3); - } -``` - -## Commands & Event Handlers - -Commands and event handlers are a way to handle commands and events sent by the user, for example, when the user -sends the `/start` command, you can send a welcome message to the user. - - -### Commands - -The library provides a way to handle commands and events using the `TgBotLib\Bot` class, for example, to handle -the `/start` command, you can use the `setCommandHandler` method: - -```php -setCommandHandler('start', new \commands\StartCommand()); -``` - -The `setCommandHandler` method takes two arguments, the first being the command name (without the `/` prefix), and -the second being a class that implements the `TgBotLib\Interfaces\CommandInterface` interface. - -The interface has only one method, `handle`, which takes two arguments, the first being an instance of the -`TgBotLib\Bot` class which is used to invoke the API without having to recreate the instance, and the second being -the update object. The update object is an instance of the `TgBotLib\Objects\Telegram\Update` class, which contains -all the information about the update. - -```php -sendMessage($update->getMessage()->getChat()->getId(), 'Hello World!'); - } - } -``` - -### Event Handlers - -Event handles are similarly implemented, but instead of using the `setCommandHandler` method, you use the -`setEventHandler` method: - -```php -setEventHandler('message', new \events\MessageEvent()); -``` - -And the interface EventInterface is used instead of CommandInterface: - -```php -sendMessage($update->getMessage()->getChat()->getId(), 'Hello World!'); - } - } -``` +Documentation will be redone # License