Skip to content

Commit 713686d

Browse files
noplanmannoplanman
committed
First version of the readme.
[skip ci]
1 parent 2b381d1 commit 713686d

File tree

1 file changed

+176
-2
lines changed

1 file changed

+176
-2
lines changed

‎README.md

Lines changed: 176 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,176 @@
1-
# php-telegram-bot-manager
2-
PHP Telegram Bot Manager
1+
# PHP Telegram Bot Manager
2+
3+
[![Scrutinizer Code Quality](https://img.shields.io/scrutinizer/g/noplanman/php-telegram-bot-manager.svg?maxAge=2592000)](https://scrutinizer-ci.com/g/noplanman/php-telegram-bot-manager/?branch=master)
4+
[![Codecov](https://img.shields.io/codecov/c/github/noplanman/php-telegram-bot-manager.svg?maxAge=2592000)](https://codecov.io/gh/noplanman/php-telegram-bot-manager)
5+
[![Build Status](https://img.shields.io/travis/noplanman/php-telegram-bot-manager.svg?maxAge=2592000)](https://travis-ci.org/noplanman/php-telegram-bot-manager)
6+
7+
[![Latest Stable Version](https://img.shields.io/packagist/v/noplanman/telegram-bot-manager.svg?maxAge=2592000)](https://packagist.org/packages/noplanman/telegram-bot-manager)
8+
[![Total Downloads](https://img.shields.io/packagist/dt/noplanman/telegram-bot-manager.svg?maxAge=2592000)](https://packagist.org/packages/noplanman/telegram-bot-manager)
9+
[![License](https://img.shields.io/packagist/l/noplanman/telegram-bot-manager.svg?maxAge=2592000)](https://github.com/noplanman/php-telegram-bot-manager/LICENSE.md)
10+
11+
This project builds on top of [PHP Telegram Bot](https://github.com/akalongman/php-telegram-bot/) and as such, depends on it!
12+
13+
The main purpose of this mini-library is to make the interaction between your webserver and Telegram easier.
14+
I strongly suggest your read the PHP Telegram Bot [instructions](https://github.com/noplanman/php-telegram-bot#instructions) first, to understand what this library does exactly.
15+
16+
Installation and usage is pretty straight forward:
17+
18+
### Require this package with [Composer](https://getcomposer.org/)
19+
20+
Either run this command in your command line:
21+
22+
```
23+
composer require noplanman/telegram-bot-manager
24+
```
25+
26+
**or**
27+
28+
For existing Composer projects, edit your project's `composer.json` file to require `noplanman/telegram-bot-manager`:
29+
30+
```js
31+
"require": {
32+
"noplanman/telegram-bot-manager": "*"
33+
}
34+
```
35+
and then run `composer update`
36+
37+
**NOTE:** This will automatically also install PHP Telegram Bot into your project (if it isn't already).
38+
39+
### Performing actions
40+
41+
What use would this library be if you couldn't perform any actions?!
42+
43+
There are 3 parameters available to get things rolling:
44+
45+
Parameter | Description
46+
----------|------------
47+
s | **s**ecret: This is a special secret value defined in the main `manager.php` file.
48+
| This parameter is required to call the script via browser!
49+
a | **a**ction: The actual action to perform. (handle (default), set, unset, reset)
50+
| **handle** executes the `getUpdates` method; **set** / **unset** / **reset** the Webhook.
51+
l | **l**oop: Number of seconds to loop the script for (used for getUpdates method).
52+
| This would be used mainly via CLI, to continually get updates for a certain period.
53+
54+
#### via browser
55+
56+
Simply point your browser to the `manager.php` file with the necessary **GET** parameters:
57+
`http://example.com/manager.php?s=<secret>&a=<action>&l=<loop>`
58+
59+
*e.g.* Set the webhook:
60+
`http://example.com/manager.php?s=super_secret&a=set`
61+
62+
*e.g.* Handle updates for 30 seconds:
63+
`http://example.com/manager.php?s=super_secret&a=handle&l=30` or simply
64+
`http://example.com/manager.php?s=super_secret&l=30` (`handle` action is the default)
65+
66+
#### via CLI
67+
68+
When using CLI, the secret is not necessary (since it could just be read from the file itself).
69+
70+
Call the `manager.php` file directly using `php` and pass the parameters:
71+
`$ php manager.php a=<action> l=<loop>`
72+
73+
*e.g.* Set the webhook:
74+
`$ php manager.php a=set`
75+
76+
*e.g.* Handle updates for 30 seconds:
77+
`$ php manager.php a=handle l=30` or simply
78+
`$ php manager.php l=30` (`handle` action is the default)
79+
80+
### Create the manager PHP file
81+
82+
You can name this file whatever you like, it just has to be somewhere inside your PHP project (preferably in the root folder to make things easier).
83+
(Let's assume our file is called `manager.php`)
84+
85+
Let's start off with a simple example that uses the Webhook method:
86+
```php
87+
<?php
88+
89+
use NPM\TelegramBotManager\BotManager;
90+
91+
// Load composer.
92+
require __DIR__ . '/vendor/autoload.php';
93+
94+
try {
95+
$bot = new BotManager([
96+
// Vitals!
97+
'api_key' => 'my_api_key',
98+
'botname' => 'my_own_bot',
99+
'secret' => 'super_secret',
100+
101+
// Extras.
102+
'webhook' => 'https://example.com/manager.php',
103+
]);
104+
$bot->run();
105+
} catch (\Exception $e) {
106+
echo $e->getMessage() . PHP_EOL;
107+
}
108+
```
109+
110+
### Set vital bot parameters
111+
112+
The vital parameters are:
113+
- Bot API key
114+
- Bot name
115+
- A secret
116+
117+
What secret you ask? Well, this is a user-defined key that is required to execute any of the library features.
118+
Best make it long, random and very unique!
119+
120+
For 84 random characters:
121+
- If you have `pwgen` installed, just execute `pwgen 84` and choose any one.
122+
- Or just go [here](https://www.random.org/strings/?num=7&len=12&digits=on&upperalpha=on&loweralpha=on&unique=on&format=plain&rnd=new) and put all the output onto a single line.
123+
124+
(You get 2 guesses why 84 is a good number :wink:)
125+
126+
### Set extra bot parameters
127+
128+
Apart from the necessary vital parameters, the bot can be easily configured using extra parameters.
129+
130+
Enable admins? Add custom command paths? Set up logging?
131+
--> All no problem!
132+
133+
Here is a list of available extra parameters:
134+
135+
Parameter | Description
136+
--------- |------------
137+
webhook | URL to the manager PHP file used for setting up the Webhook.
138+
| *e.g.* `'https://example.com/manager.php'`
139+
selfcrt | Path to a self-signed certificate (if necessary).
140+
| *e.g.* `__DIR__ . '/server.crt'`
141+
logging | Path(s) where to the log files should be put. This is an array that can contain all 3 log file paths (`error`, `debug` and `update`).
142+
| *e.g.* `['error' => __DIR__ . '/php-telegram-bot-error.log']`
143+
admins | An array of user ids that have admin access to your bot.
144+
| *e.g.* `[12345]`
145+
mysql | Mysql credentials to connect a database (necessary for [`getUpdates`](#using-getupdates-method) method!).
146+
| *e.g.* `['host' => '127.0.0.1', 'user' => 'root', 'password' => 'root', 'database' => 'telegram_bot']`
147+
download_path | Custom download path.
148+
| *e.g.* `__DIR__ . '/Download'`
149+
upload_path | Custom upload path.
150+
| *e.g.* `__DIR__ . '/Upload'`
151+
commands_paths | A list of custom commands paths.
152+
| *e.g.* `[__DIR__ . '/CustomCommands']`
153+
command_configs | A list of all custom command configs.
154+
| *e.g.* `['sendtochannel' => ['your_channel' => '@my_channel']`
155+
botan_token | The Botan.io token to be used for analytics.
156+
| *e.g.* `'botan_12345'`
157+
custom_input | Override the custom input of your bot (mostly for testing purposes!).
158+
| *e.g.* `'{"some":"raw", "json":"update"}'`
159+
160+
### Using getUpdates method
161+
162+
Using the `getUpdates` method requires a MySQL database connection:
163+
```php
164+
$bot = new BotManager([
165+
...
166+
// Extras.
167+
'mysql' => [
168+
'host' => '127.0.0.1',
169+
'user' => 'root',
170+
'password' => 'root',
171+
'database' => 'telegram_bot',
172+
],
173+
]);
174+
```
175+
176+
Now, the updates can be done either through the [browser](#via-browser) or [via CLI](#via-cli).

0 commit comments

Comments
 (0)