Skip to content

Commit 00da3af

Browse files
BushlanovDevBushlanovDev
committed
Documentation and some fix
1 parent ea19472 commit 00da3af

File tree

6 files changed

+154
-20
lines changed

6 files changed

+154
-20
lines changed

‎README.md‎

Lines changed: 32 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,11 @@ composer require bushlanov-dev/max-bot-api-client-php
3131
Отправка сообщения с клавиатурой
3232

3333
```php
34-
$api = new \BushlanovDev\MaxMessengerBot\Api('YOUR_BOT_API_TOKEN');
34+
require __DIR__.'/vendor/autoload.php';
35+
36+
use BushlanovDev\MaxMessengerBot\Api;
37+
38+
$api = new Api('YOUR_BOT_API_TOKEN');
3539

3640
$api->sendMessage(
3741
userId: 123, // ID пользователя получателя сообщения
@@ -47,6 +51,26 @@ $api->sendMessage(
4751
);
4852
```
4953

54+
Создание универсального обработчика обновлений
55+
56+
```php
57+
$dispatcher = $api->getUpdateDispatcher();
58+
59+
$dispatcher->onMessageCreated(function (MessageCreatedUpdate $update, Api $api) {
60+
$api->sendMessage(
61+
userId: $update->message->recipient->userId,
62+
text: 'Привет!',
63+
);
64+
});
65+
// или
66+
$dispatcher->addHandler(UpdateType::BotStarted, function (BotStartedUpdate $update, Api $api) {
67+
$api->sendMessage(
68+
chatId: $update->chatId,
69+
text: 'Я запущен!',
70+
);
71+
});
72+
```
73+
5074
Подписка на вэб хуки
5175

5276
```php
@@ -61,19 +85,18 @@ $api->subscribe(
6185
);
6286
```
6387

64-
Обработка хуков
88+
Обработка обновлений
6589

6690
```php
67-
$webhookHandler = $api->createWebhookHandler();
91+
$handler = $api->createWebhookHandler('super_secret'); // Обновления через вебхук
92+
// ИЛИ
93+
$handler = $api->createLongPollingHandler(); // Обновления через лонгполлинг
6894

69-
$webhookHandler->addHandler(UpdateType::BotStarted, function (BotStartedUpdate $update, Api $api) {
70-
$api->sendMessage(
71-
chatId: $update->chatId,
72-
text: 'Я запущен!',
73-
);
74-
});
95+
$handler->handle();
7596
```
7697

98+
> ℹ️ С полной документацией [вы можете ознакомиться тут](./docs/README.md).
99+
77100
## Реализованные методы
78101

79102
#### Bots

‎docs/README.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
- [Быстрый старт](#Быстрый-старт)
2+
- [Получение токена](#Получение-токена)
3+
- [Установка библиотеки](#Установка-библиотеки)
4+
- [Инициализация бота](#Инициализация-бота)
5+
- [Информация о боте](#Информация-о-боте)
6+
- `GET /me` (`getBotInfo`) - [*Получение информации о боте.*](#Получение-информации-о-боте)
7+
- `PATCH /me` (`editBotInfo`) - [*Редактирование информации о боте.*](#Редактирование-информации-о-боте)
8+
- Чаты
9+
- `GET /chats` (`getChats`) - *Получение списка всех чатов бота.*
10+
- `GET /chats/{chatLink}` (`getChatByLink`) - *Получение информации о чате по ссылке.*
11+
- `GET /chats/{chatId}` (`getChat`) - *Получение информации о чате по ID.*
12+
- `PATCH /chats/{chatId}` (`editChat`) - *Редактирование информации о чате.*
13+
- `DELETE /chats/{chatId}` (`deleteChat`) - *Удаление чата.*
14+
- `POST /chats/{chatId}/actions` (`sendAction`) - *Отправка действия в чат (например, "печатает...").*
15+
- `GET /chats/{chatId}/pin` (`getPinnedMessage`) - *Получение закрепленного сообщения.*
16+
- `PUT /chats/{chatId}/pin` (`pinMessage`) - *Закрепление сообщения.*
17+
- `DELETE /chats/{chatId}/pin` (`unpinMessage`) - *Открепление сообщения.*
18+
- `GET /chats/{chatId}/members/me` (`getMembership`) - *Получение информации о членстве бота в чате.*
19+
- `DELETE /chats/{chatId}/members/me` (`leaveChat`) - *Выход бота из чата.*
20+
- `GET /chats/{chatId}/members/admins` (`getAdmins`) - *Получение администраторов чата.*
21+
- `POST /chats/{chatId}/members/admins` (`addAdmins`) - *Назначение администраторов чата.*
22+
- `DELETE /chats/{chatId}/members/admins/{userId}` (`deleteAdmins`) - *Снятие прав администратора.*
23+
- `GET /chats/{chatId}/members` (`getMembers`) - *Получение участников чата.*
24+
- `POST /chats/{chatId}/members` (`addMembers`) - *Добавление участников в чат.*
25+
- `DELETE /chats/{chatId}/members` (`deleteMember`) - *Удаление участника из чата.*
26+
- Получение обновлений
27+
- `GET /subscriptions` (`getSubscriptions`) - *Получение списка Webhook-подписок.*
28+
- `POST /subscriptions` (`subscribe`) - *Создание Webhook-подписки.*
29+
- `DELETE /subscriptions` (`unsubscribe`) - *Удаление Webhook-подписки.*
30+
- `GET /updates` (`getUpdates`) - *Получение обновлений через Long-Polling.*
31+
- Загрузка файлов
32+
- `POST /uploads` (`getUploadUrl`) - *Получение URL для загрузки файла.*
33+
- Сообщения
34+
- `GET /messages` (`getMessages`) - *Получение списка сообщений из чата.*
35+
- `POST /messages` (`sendMessage`) - *Отправка сообщения.*
36+
- `PUT /messages` (`editMessage`) - *Редактирование сообщения.*
37+
- `DELETE /messages` (`deleteMessage`) - *Удаление сообщения.*
38+
- `GET /messages/{messageId}` (`getMessageById`) - *Получение сообщения по ID.*
39+
- `GET /videos/{videoToken}` (`getVideoAttachmentDetails`) - *Получение детальной информации о видео.*
40+
- `POST /answers` (`answerOnCallback`) - *Ответ на нажатие callback-кнопки.*
41+
42+
## Быстрый старт
43+
44+
> Если вы новичок, то можете прочитать [официальную документацию](https://dev.max.ru/), написанную разработчиками Max.
45+
46+
### Получение токена
47+
48+
Откройте диалог с [MasterBot](https://max.ru/MasterBot), следуйте инструкциям и создайте нового бота. После создания
49+
бота MasterBot отправит вам токен.
50+
51+
### Установка библиотеки
52+
53+
```bash
54+
composer require bushlanov-dev/max-bot-api-client-php
55+
```
56+
57+
### Инициализация бота
58+
59+
Единственной обязательной настройкой является токен вашего бота.
60+
⚠️ Никогда, и ни при каких обстоятельствах не храните токен в коде. ⚠️
61+
Используйте переменные окружения!
62+
63+
```php
64+
require __DIR__.'/vendor/autoload.php';
65+
66+
use BushlanovDev\MaxMessengerBot\Api;
67+
68+
$api = new Api('YOUR_BOT_API_TOKEN');
69+
```
70+
71+
Так же вы можете создать экземпляр бота гибко настроив все зависимости под свои нужды.
72+
73+
```php
74+
$api = new Api(
75+
client: new Client(...),
76+
modelFactory: new ModelFactory(),
77+
logger: new YourPsrLogger(),
78+
);
79+
```
80+
81+
## Информация о боте
82+
83+
### Получение информации о боте
84+
85+
```php
86+
$botInfo = $api->getBotInfo();
87+
```
88+
89+
### Редактирование информации о боте
90+
91+
Обратите внимание что данный метод отправляется PATCH запросом. Это значит, что будут обновлены только переданные
92+
поля.
93+
В следующем примере мы изменяем только название бота и отчистим его описание. Остальные поля останутся неизменными.
94+
95+
```php
96+
$botInfo = $api->editBotInfo(
97+
new BotPatch(
98+
name: 'Супер бот',
99+
description: null,
100+
)
101+
);
102+
```

‎src/Api.php‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@
4747
*/
4848
class Api
4949
{
50-
public const string LIBRARY_VERSION = '1.0.0';
50+
public const string LIBRARY_VERSION = '1.0.1';
5151

5252
public const string API_VERSION = '0.0.6';
5353

@@ -85,21 +85,23 @@ class Api
8585
/**
8686
* Api constructor.
8787
*
88-
* @param string $accessToken Your bot's access token from @MasterBot.
88+
* @param string|null $accessToken Your bot's access token from @MasterBot.
8989
* @param ClientApiInterface|null $client Http api client.
9090
* @param ModelFactory|null $modelFactory The model factory.
9191
* @param LoggerInterface|null $logger PSR LoggerInterface.
92-
* @param UpdateDispatcher|null $updateDispatcher The update dispatcher.
9392
*
9493
* @throws InvalidArgumentException
9594
*/
9695
public function __construct(
97-
string $accessToken,
96+
?string $accessToken = null,
9897
?ClientApiInterface $client = null,
9998
?ModelFactory $modelFactory = null,
10099
?LoggerInterface $logger = null,
101-
?UpdateDispatcher $updateDispatcher = null,
102100
) {
101+
if (empty($accessToken) && $client === null) {
102+
throw new InvalidArgumentException('You must provide either an access token or a client.');
103+
}
104+
103105
$this->logger = $logger ?? new NullLogger();
104106

105107
if ($client === null) {
@@ -130,7 +132,7 @@ public function __construct(
130132

131133
$this->client = $client;
132134
$this->modelFactory = $modelFactory ?? new ModelFactory();
133-
$this->updateDispatcher = $updateDispatcher ?? new UpdateDispatcher($this);
135+
$this->updateDispatcher = new UpdateDispatcher($this);
134136
}
135137

136138
/**

‎src/Laravel/MaxBotServiceProvider.php‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,6 @@ public function register(): void
102102
$app->make(ClientApiInterface::class),
103103
$app->make(ModelFactory::class),
104104
$app->make(LoggerInterface::class),
105-
null,
106105
);
107106
});
108107

‎tests/ApiFactoryMethodsTest.php‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -35,15 +35,11 @@ protected function setUp(): void
3535
$this->modelFactoryMock = $this->createMock(ModelFactory::class);
3636
$this->loggerMock = $this->createMock(LoggerInterface::class);
3737

38-
$apiForDispatcher = $this->createMock(Api::class);
39-
$dispatcher = new UpdateDispatcher($apiForDispatcher);
40-
4138
$this->api = new Api(
4239
'fake-token',
4340
$this->clientMock,
4441
$this->modelFactoryMock,
4542
$this->loggerMock,
46-
$dispatcher,
4743
);
4844
}
4945

‎tests/ApiTest.php‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1980,4 +1980,16 @@ public function getVideoAttachmentDetailsCallsClientCorrectly(): void
19801980

19811981
$this->assertSame($expectedDetails, $result);
19821982
}
1983+
1984+
#[Test]
1985+
public function constructorThrowsExceptionWhenNoTokenAndNoClientProvided(): void
1986+
{
1987+
$this->expectException(InvalidArgumentException::class);
1988+
$this->expectExceptionMessage('You must provide either an access token or a client.');
1989+
1990+
new Api(
1991+
accessToken: null,
1992+
client: null
1993+
);
1994+
}
19831995
}

0 commit comments

Comments
 (0)