Refactor README: Remove detailed sections

This commit is contained in:
netkas 2024-11-04 00:58:24 -05:00
parent e88e18995e
commit 3e860ea089

281
README.md
View file

@ -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)
<!-- TOC -->
@ -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('<BOT TOKEN>');
/** @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: '<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
<?php
// Import ncc
require 'ncc';
import('net.nosial.tgbotlib');
// Require commands & event handlers
require 'commands' . DIRECTORY_SEPARATOR . 'StartCommand.php';
require 'commands' . DIRECTORY_SEPARATOR . 'HashCommand.php';
// Create a new instance of the bot
$bot = new TgBotLib\BotOld(getenv('BOT_TOKEN'));
// Loop forever
while(true)
{
/** @var \TgBotLib\Objects\Update $update */
foreach ($bot->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
<?php
// Import ncc
require 'ncc';
// Import packages
import('net.nosial.tgbotlib');
import('net.nosial.tamerlib');
// Require commands
require 'commands' . DIRECTORY_SEPARATOR . 'StartCommand.php';
require 'commands' . DIRECTORY_SEPARATOR . 'HashCommand.php';
// Initialize the bot
$bot = new TgBotLib\BotOld('<BOT TOKEN>');
// 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
<?php
// Import ncc
require 'ncc';
// Import packages
import('net.nosial.tgbotlib');
import('net.nosial.tamerlib');
$bot = new TgBotLib\BotOld('<BOT TOKEN>');
\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
<?php
require 'ncc';
import('net.nosial.tgbotlib');
$bot = new TgBotLib\BotOld(getenv('BOT_TOKEN'));
$bot->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
<?php
namespace commands;
use TgBotLib\BotOld;use TgBotLib\Interfaces\CommandInterface;use TgBotLib\Objects\Update;
class StartCommand extends CommandInterface
{
public function handle(BotOld $bot, Update $update): void
{
$bot->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
<?php
require __DIR__ . DIRECTORY_SEPARATOR . 'autoload.php';
$bot = new TgBotLib\BotOld(getenv('BOT_TOKEN'));
$bot->setEventHandler('message', new \events\MessageEvent());
```
And the interface EventInterface is used instead of CommandInterface:
```php
<?php
namespace events;
use TgBotLib\BotOld;use TgBotLib\Interfaces\EventInterface;use TgBotLib\Objects\Update;
class MessageEvent implements EventInterface
{
public function handle(BotOld $bot, Update $update): void
{
$bot->sendMessage($update->getMessage()->getChat()->getId(), 'Hello World!');
}
}
```
Documentation will be redone
# License