Skip to content

Commit d6f8f3f

Browse files
TiiFuchsTiiFuchs
committed
Added first draft of documentation
1 parent 1c93b31 commit d6f8f3f

File tree

1 file changed

+199
-0
lines changed

1 file changed

+199
-0
lines changed

‎README.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
<div id="top"></div>
2+
3+
![Bot API][bot-api-shield]
4+
![Tests][tests-shield]
5+
6+
<!-- TABLE OF CONTENTS -->
7+
<details>
8+
<summary>Table of Contents</summary>
9+
<ol>
10+
<li><a href="#installation">Installation</a></li>
11+
<li>
12+
<a href="#usage">Usage</a>
13+
<ol>
14+
<li><a href="#defining-a-keyboard">Defining a Keyboard</a></li>
15+
<li><a href="#defining-buttons">Defining Buttons</a></li>
16+
<li>
17+
<a href="#bind-buttons-to-a-keyboard">Bind Buttons to a Keyboard</a>
18+
<ol>
19+
<li><a href="#by-row">By Row</a></li>
20+
<li><a href="#by-button">By Button</a></li>
21+
</ol>
22+
</li>
23+
<li><a href="#force-reply-and-reply-keyboard-remove">ForceReply and ReplyKeyboardRemove</a></li>
24+
<li><a href="#keyboard-button-poll-type">KeyboardButtonPollType</a></li>
25+
</ol>
26+
</li>
27+
</ol>
28+
</details>
29+
30+
## Installation
31+
32+
Install the package using composer:
33+
34+
```shell
35+
composer require php-telegram-bot/fluent-keyboard
36+
```
37+
38+
<p align="right">(<a href="#top">back to top</a>)</p>
39+
40+
## Usage
41+
42+
If you need to create a keyboard you can use the classes provided by this package as a drop-in replacement.
43+
44+
This is best explained with an example:
45+
46+
```php
47+
Request::sendMessage([
48+
'chat_id' => 12345,
49+
'text' => 'Keyboard Example',
50+
'reply_markup' => ReplyKeyboardMarkup::make()
51+
->oneTimeKeyboard()
52+
->button(KeyboardButton::make('Cancel'))
53+
->button(KeyboardButton::make('OK')),
54+
]);
55+
```
56+
57+
A ReplyKeyboardMarkup is created by calling the static make method on `ReplyKeyboardMarkup` after that every field,
58+
like `one_time_keyboard` you want to set can be chained by calling it in camelCase. Buttons can be added by calling
59+
the `button` method. We have a detailed look on that later.
60+
61+
The classes and fields are named after the corresponding type and fields of
62+
the [Telegram Bot API](https://core.telegram.org/bots/api).
63+
64+
<p align="right">(<a href="#top">back to top</a>)</p>
65+
66+
### Defining a Keyboard
67+
68+
You can create a keyboard by calling the static `make()` method on its class.
69+
70+
After that you can chain methods to set additional fields that are available in the Bot API. This is done by calling the
71+
field name in camelCase. So instead of input_field_placeholder, you need to call `inputFieldPlaceholder()`.
72+
73+
```php
74+
ReplyKeyboardMarkup::make()
75+
->inputFieldPlaceholder('Placeholder');
76+
```
77+
78+
<p align="right">(<a href="#top">back to top</a>)</p>
79+
80+
### Defining Buttons
81+
82+
The Buttons are created in the same way:
83+
84+
```php
85+
KeyboardButton::make()
86+
->text('Text of Button')
87+
->requestContact();
88+
```
89+
90+
As a shortcut, you can pass the mandatory `text` field as an argument of the static `make()` method like this:
91+
92+
```php
93+
KeyboardButton::make('Text of Button')
94+
->requestContact();
95+
```
96+
97+
This is done the same way for `InlineKeyboardButton`:
98+
99+
```php
100+
InlineKeyboardButton::make('Button Text')
101+
->callbackData('button-1');
102+
```
103+
104+
To find out which fields are available have a look at the [Bot API documentation](https://core.telegram.org/bots/api).
105+
106+
<p align="right">(<a href="#top">back to top</a>)</p>
107+
108+
### Bind Buttons to a Keyboard
109+
110+
The keyboard does not work without any buttons, so you need to pass the buttons to the keyboard. There are a few ways to
111+
do this.
112+
113+
#### By Row
114+
115+
```php
116+
ReplyKeyboardMarkup::make()
117+
->row([
118+
KeyboardButton::make('Cancel'),
119+
KeyboardButton::make('OK')
120+
]);
121+
```
122+
123+
If you need more than one row, call `row()` multiple times:
124+
125+
```php
126+
InlineKeyboardMarkup::make()
127+
->row([
128+
InlineKeyboardButton::make('1')->callbackData('page-1'),
129+
InlineKeyboardButton::make('2')->callbackData('page-2'),
130+
InlineKeyboardButton::make('3')->callbackData('page-3')
131+
])
132+
->row([
133+
InlineKeyboardButton::make('prev')->callbackData('page-prev'),
134+
InlineKeyboardButton::make('next')->callbackData('page-next')
135+
]);
136+
```
137+
138+
#### By Button
139+
140+
```php
141+
ReplyKeyboardMarkup::make()
142+
->button(KeyboardButton::make('First Button'))
143+
->button(KeyboardButton::make('Second Button'));
144+
```
145+
146+
If you need more than one row, just call the row method without arguments, and continue calling `button()`:
147+
148+
```php
149+
InlineKeyboardMarkup::make()
150+
->button(InlineKeyboardButton::make('A')->callbackData('answer-a'))
151+
->button(InlineKeyboardButton::make('B')->callbackData('answer-b'))
152+
->row()
153+
->button(InlineKeyboardButton::make('C')->callbackData('answer-c'))
154+
->button(InlineKeyboardButton::make('D')->callbackData('answer-d'));
155+
```
156+
157+
It's up to you if you define your buttons inline like in these examples or you'd like to generate a whole row before and
158+
pass the variable to the `row()` method.
159+
160+
<p align="right">(<a href="#top">back to top</a>)</p>
161+
162+
### ForceReply and ReplyKeyboardRemove
163+
164+
ForceReply and ReplyKeyboardRemove can be used the same way as a normal keyboard, but the do not receive any buttons:
165+
166+
```php
167+
$this->replyToUser('Thank you', [
168+
'reply_markup' => ReplyKeyboardRemove::make()->selective(),
169+
]);
170+
```
171+
172+
```php
173+
$data['reply_markup'] = ForceReply::make()->inputFieldPlaceholder('Please type something...');
174+
```
175+
176+
<p align="right">(<a href="#top">back to top</a>)</p>
177+
178+
### KeyboardButtonPollType
179+
180+
The request_poll field is a little special. You can specify which poll type the user can create by passing
181+
a `KeyboardButtonPollType` object.
182+
183+
```php
184+
KeyboardButton::make()->requestPoll(KeyboardButtonPollType::regular())
185+
```
186+
187+
The `KeyboardButtonPollType` class has static methods for each possible type. But if there are new types in the future
188+
you don't have to wait until we release an update. You can either pass the array structure directly to
189+
the `requestPoll()` method or you pass the array structure to the constructor of `KeyboardButtonPollType`.
190+
191+
```php
192+
$pollButton = new KeyboardButtonPollType([
193+
'type' => 'quiz'
194+
]);
195+
```
196+
197+
[tests-shield]: https://img.shields.io/github/workflow/status/php-telegram-bot/fluent-keyboard/Tests?label=Tests&style=for-the-badge
198+
199+
[bot-api-shield]: https://img.shields.io/badge/Bot%20API-5.7%20(Jan%202022)-%232a9ed6?style=for-the-badge

0 commit comments

Comments
 (0)