From ef2b68a5e9d2fe4f155d397ccf23f812875c9bbf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Armando=20L=C3=BCscher?= Date: Tue, 25 Jul 2017 17:36:49 +0200 Subject: [PATCH] Update readme text and all code references, examples, links etc. to state of 0.46.0. Fix #567 --- CHANGELOG.md | 1 + README.md | 264 +++++++++++++++++++++++++++++---------------------- 2 files changed, 154 insertions(+), 111 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 15636bb3f..4172edf7e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c ## [Unreleased] ### Added ### Changed +- Updated readme to latest state of 0.46.0. ### Deprecated ### Removed ### Fixed diff --git a/README.md b/README.md index 571a47914..89b2edd7f 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ -A Telegram Bot based on the official [Telegram Bot API](https://core.telegram.org/bots/api) +A Telegram Bot based on the official [Telegram Bot API][Telegram-Bot-API] ## Table of Contents - [Introduction](#introduction) @@ -152,9 +152,8 @@ group. This step is up to you actually. ### Require this package with Composer -Install this package through [Composer](https://getcomposer.org/). -Edit your project's `composer.json` file to require -`longman/telegram-bot`. +Install this package through [Composer][composer]. +Edit your project's `composer.json` file to require `longman/telegram-bot`. Create *composer.json* file ```json @@ -162,7 +161,7 @@ Create *composer.json* file "name": "yourproject/yourproject", "type": "project", "require": { - "php": ">=5.6", + "php": ">=5.5", "longman/telegram-bot": "*" } } @@ -179,7 +178,7 @@ composer require longman/telegram-bot ### Choose how to retrieve Telegram updates -The bot can handle updates with **webhook** or **getUpdate** method: +The bot can handle updates with **Webhook** or **getUpdates** method: | | Webhook | getUpdate | | ---- | :----: | :----: | @@ -190,21 +189,24 @@ The bot can handle updates with **webhook** or **getUpdate** method: ## Webhook installation -In order to set a [Webhook](https://core.telegram.org/bots/api#setwebhook) you need a server with https and composer support. +Note: For a more detailed explanation, head over to the [example-bot repository][example-bot-repository] and follow the instructions there. + +In order to set a [Webhook][api-setwebhook] you need a server with HTTPS and composer support. (For a [self signed certificate](#self-signed-certificate) you need to add some extra code) -Create *set.php* (or just copy and edit *examples/set.php*) and put into it: +Create [*set.php*][set.php] with the following contents: ```php setWebhook($hook_url); @@ -212,30 +214,33 @@ try { echo $result->getDescription(); } } catch (Longman\TelegramBot\Exception\TelegramException $e) { - echo $e; + // log telegram errors + // echo $e->getMessage(); } ``` Open your *set.php* via the browser to register the webhook with Telegram. +You should see `Webhook was set`. -Now, create *hook.php* (or just copy and edit *examples/hook.php*) and put into it: +Now, create [*hook.php*][hook.php] with the following contents: ```php handle(); } catch (Longman\TelegramBot\Exception\TelegramException $e) { // Silence is golden! // log telegram errors - // echo $e; + // echo $e->getMessage(); } ``` @@ -243,25 +248,25 @@ try { To upload the certificate, add the certificate path as a parameter in *set.php*: ```php -$result = $telegram->setWebhook($hook_url, ['certificate' => $certificate_path]); +$result = $telegram->setWebhook($hook_url, ['certificate' => '/path/to/certificate']); ``` ### Unset Webhook -Edit *example/unset.php* with your bot credentials and execute it. +Edit [*unset.php*][unset.php] with your bot credentials and execute it. -### getUpdate installation +### getUpdates installation -The MySQL database must be active! +The MySQL database must be enabled for the getUpdates method! -Create *getUpdateCLI.php* (or just copy and edit *examples/getUpdateCLI.php*) and put into it: +Create [*getUpdatesCLI.php*][getUpdatesCLI.php] with the following contents: ```php #!/usr/bin/env php 'localhost', 'user' => 'dbuser', @@ -271,26 +276,27 @@ $mysql_credentials = [ try { // Create Telegram API object - $telegram = new Longman\TelegramBot\Telegram($API_KEY, $BOT_NAME); + $telegram = new Longman\TelegramBot\Telegram($bot_api_key, $bot_username); // Enable MySQL - $telegram->enableMySQL($mysql_credentials); + $telegram->enableMySql($mysql_credentials); // Handle telegram getUpdate request $telegram->handleGetUpdates(); } catch (Longman\TelegramBot\Exception\TelegramException $e) { // log telegram errors - echo $e; + // echo $e->getMessage(); } ``` -give the file permission to execute: -``` -chmod 775 getUpdateCLI.php -``` -then run +Next, give the file permission to execute: +```bash +$ chmod +x getUpdatesCLI.php ``` -./getUpdateCLI.php + +Lastly, run it! +```bash +$ ./getUpdatesCLI.php ``` ## Support @@ -317,14 +323,17 @@ $result = Request::sendMessage(['chat_id' => $chat_id, 'text' => 'Your utf8 text #### Send Photo -To send a local photo, provide the file path as the second parameter: +To send a local photo, add it properly to the `$data` parameter using the file path: ```php -$data = ['chat_id' => $chat_id]; -$result = Request::sendPhoto($data, $telegram->getUploadPath() . '/image.jpg'); +$data = [ + 'chat_id' => $chat_id, + 'photo' => Request::encodeFile('/path/to/pic.jpg'), +]; +$result = Request::sendPhoto($data); ``` -If you know the `file_id` of a previously uploaded file, just include it in the data array: +If you know the `file_id` of a previously uploaded file, just use it directly in the data array: ```php $data = [ @@ -334,8 +343,18 @@ $data = [ $result = Request::sendPhoto($data); ``` -*sendAudio*, *sendDocument*, *sendSticker*, *sendVideo* and *sendVoice* all work in the same way. -See *examples/Commands/ImageCommand.php* for a full example. +To send a remote photo, use the direct URL instead: + +```php +$data = [ + 'chat_id' => $chat_id, + 'photo' => 'https://example.com/path/to/pic.jpg', +]; +$result = Request::sendPhoto($data); +``` + +*sendAudio*, *sendDocument*, *sendSticker*, *sendVideo*, *sendVoice* and *sendVideoNote* all work in the same way, just check the [API documentation](https://core.telegram.org/bots/api#sendphoto) for the exact usage. +See the [*ImageCommand.php*][ImageCommand.php] for a full example. #### Send Chat Action @@ -345,27 +364,28 @@ Request::sendChatAction(['chat_id' => $chat_id, 'action' => 'typing']); #### getUserProfilePhoto -Retrieve the user photo, see *src/Commands/WhoamiCommand.php* for a full example. +Retrieve the user photo, see [*WhoamiCommand.php*][WhoamiCommand.php] for a full example. -#### getFile and dowloadFile +#### getFile and downloadFile -Get the file path and download it, see *src/Commands/WhoamiCommand.php* for a full example. +Get the file path and download it, see [*WhoamiCommand.php*][WhoamiCommand.php] for a full example. #### Send message to all active chats To do this you have to enable the MySQL connection. -Here's an example of use: +Here's an example of use (check [`DB::selectChats()`][DB::selectChats] for parameter usage): ```php $results = Request::sendToActiveChats( - 'sendMessage', // callback function to execute (see Request.php for available methods) - ['text' => 'Hey! Check out the new features!!'], // Data to pass to the request - true, // Send to chats (group chat) - true, // Send to chats (super group chat) - true, // Send to users (single chat) - null, // 'yyyy-mm-dd hh:mm:ss' date range from - null // 'yyyy-mm-dd hh:mm:ss' date range to - ); + 'sendMessage', // Callback function to execute (see Request.php methods) + ['text' => 'Hey! Check out the new features!!'], // Param to evaluate the request + [ + 'groups' => true, + 'supergroups' => true, + 'channels' => false, + 'users' => true, + ] +); ``` You can also broadcast a message to users, from the private chat with your bot. Take a look at the [admin commands](#admin-commands) below. @@ -374,9 +394,7 @@ You can also broadcast a message to users, from the private chat with your bot. ### MySQL storage (Recommended) -If you want to save messages/users/chats for further usage -in commands, create a new database, import *structure.sql* and enable -MySQL support after object creation and BEFORE handle method: +If you want to save messages/users/chats for further usage in commands, create a new database (`utf8mb4_unicode_520_ci`), import *structure.sql* and enable MySQL support after object creation and BEFORE `handle()` method: ```php $mysql_credentials = [ @@ -386,22 +404,25 @@ $mysql_credentials = [ 'database' => 'dbname', ]; -$telegram->enableMySQL($mysql_credentials); +$telegram->enableMySql($mysql_credentials); ``` + You can set a custom prefix to all the tables while you are enabling MySQL: ```php -$telegram->enableMySQL($mysql_credentials, $BOT_NAME . '_'); +$telegram->enableMySql($mysql_credentials, $bot_username . '_'); ``` -Consider to use the *utf8mb4* branch if you find some special characters problems. -You can also store inline query and chosen inline query in the database. +You can also store inline query and chosen inline query data in the database. + #### External Database connection -Is possible to provide to the library an external mysql connection. Here's how to configure it: + +It is possible to provide the library with an external MySQL PDO connection. +Here's how to configure it: ```php -$telegram->enableExternalMysql($external_pdo_connection) -//$telegram->enableExternalMySQL($external_pdo_connection, $table_prefix) +$telegram->enableExternalMySql($external_pdo_connection) +//$telegram->enableExternalMySql($external_pdo_connection, $table_prefix) ``` ### Channels Support @@ -410,22 +431,24 @@ With [admin commands](#admin-commands) you can manage your channels directly wit ### Botan.io integration (Optional) -You can enable the integration using this line: +You can enable the integration using this line in you `hook.php`: ```php $telegram->enableBotan('your_token'); ``` -Replace ```'your_token'``` with your Botan.io token, check [this page](https://github.com/botanio/sdk#creating-an-account) to see how to obtain one. +Replace `your_token` with your Botan.io token, check [this page](https://github.com/botanio/sdk#creating-an-account) to see how to obtain one. The following actions will be tracked: - Commands (shown as `Command (/command_name)` in the stats - Inline Queries, Chosen Inline Results and Callback Queries - Messages sent to the bot (or replies in groups) -In order to use the URL shortener you must include the class ```use Longman\TelegramBot\Botan;``` and call it like this: +In order to use the URL shortener you must include the class `use Longman\TelegramBot\Botan;` and call it like this: -```Botan::shortenUrl('https://github.com/php-telegram-bot/core', $user_id);``` +```php +Botan::shortenUrl('https://github.com/php-telegram-bot/core', $user_id); +``` Shortened URLs are cached in the database (if MySQL storage is enabled). @@ -434,117 +457,117 @@ Shortened URLs are cached in the database (if MySQL storage is enabled). #### Predefined Commands The bot is able to recognise commands in a chat with multiple bots (/command@mybot). -It can execute command triggering a chat event. Here's the list: -- New chat participant (**NewchatparticipantCommand.php**) -- Left chat participant (**LeftchatparticipantCommand.php**) -- New chat title (**NewchattitleCommand.php**) -- Delete chat photo (**DeletechatphotoCommand.php**) -- Group chat created (**GroupchatcreatedCommand.php**) -- Super group chat created (**SupergroupchatcreatedCommand.php**) -- Channel chat created (**ChannelchatcreatedCommand.php**) -- Inline query (**InlinequeryCommand.php**) -- Chosen inline result (**ChoseninlineresultCommand.php**) +It can execute commands that get triggered by chat events. -**GenericCommand.php** lets you handle commands that don't exist or to -use commands as a variable: +Here's the list: -Favourite colour? **/black, /red** +- *StartCommand.php* (A new user starts to use the bot.) +- *NewChatMembersCommand.php* (A new member(s) was added to the group, information about them.) +- *LeftChatMemberCommand.php* (A member was removed from the group, information about them.) +- *NewChatTitleCommand.php* (A chat title was changed to this value.) +- *NewChatPhotoCommand.php* (A chat photo was changed to this value.) +- *DeleteChatPhotoCommand.php* (Service message: the chat photo was deleted.) +- *GroupChatCreatedCommand.php* (Service message: the group has been created.) +- *SupergroupChatCreatedCommand.php* (Service message: the supergroup has been created.) +- *ChannelChatCreatedCommand.php* (Service message: the channel has been created.) +- *MigrateToChatIdCommand.php* (The group has been migrated to a supergroup with the specified identifier.) +- *MigrateFromChatIdCommand.php* (The supergroup has been migrated from a group with the specified identifier.) +- *PinnedMessageCommand.php* (Specified message was pinned.) -Favourite number? **/1, /134** - -**GenericmessageCommand.php** lets you handle any type of message. +- *GenericmessageCommand.php* (Handle any type of message.) +- *GenericCommand.php* (Handle commands that don't exist or to use commands as a variable.) + - Favourite colour? */black, /red* + - Favourite number? */1, /134* #### Custom Commands -Maybe you would like to develop your own commands. A good practice is -to store them outside *vendor/*. This can be done using: - -```php -$commands_folder = __DIR__ . '/Commands/'; -$telegram->addCommandsPath($commands_folder); -``` +Maybe you would like to develop your own commands. +There is a guide to help you [create your own commands][wiki-create-your-own-commands]. -Inside *examples/Commands/* there are some samples that show how to use types. +Also, be sure to have a look at the [example commands][ExampleCommands-folder] to learn more about custom commands and how they work. #### Commands Configuration -With this method you can set some command specific parameters: +With this method you can set some command specific parameters, for example: ```php -//Google geocode/timezone API key for date command +// Google geocode/timezone API key for /date command $telegram->setCommandConfig('date', ['google_api_key' => 'your_google_api_key_here']); -//OpenWeatherMap API key for weather command +// OpenWeatherMap API key for /weather command $telegram->setCommandConfig('weather', ['owm_api_key' => 'your_owm_api_key_here']); ``` ### Admin Commands -Enabling this feature, the admin bot can perform some super user commands like: -- Send message to all chats */sendtoall* +Enabling this feature, the bot admin can perform some super user commands like: - List all the chats started with the bot */chats* +- Clean up old database entries */cleanup* +- Show debug information about the bot */debug* +- Send message to all chats */sendtoall* - Post any content to your channels */sendtochannel* -- inspect a user or a chat with */whois* (new!) +- Inspect a user or a chat with */whois* + +Take a look at all default admin commands stored in the [*src/Commands/AdminCommands/*][AdminCommands-folder] folder. #### Set Admins You can specify one or more admins with this option: ```php -//Single admin +// Single admin $telegram->enableAdmin(your_telegram_user_id); -//Multiple admins +// Multiple admins $telegram->enableAdmins([your_telegram_user_id, other_telegram_user_id]); ``` -Telegram user id can be retrieved with the command **/whoami**. -Admin commands are stored in *src/Admin/* folder. -To get a list of all available commands, type **/help**. +Telegram user id can be retrieved with the [*/whoami*][WhoamiCommand.php] command. #### Channel Administration To enable this feature follow these steps: -- Add your bot as channel administrator, this can be done with any telegram client. +- Add your bot as channel administrator, this can be done with any Telegram client. - Enable admin interface for your user as explained in the admin section above. -- Enter your channel name as a parameter for the */sendtochannel* command: +- Enter your channel name as a parameter for the [*/sendtochannel*][SendtochannelCommand.php] command: ```php $telegram->setCommandConfig('sendtochannel', ['your_channel' => ['@type_here_your_channel']]); ``` - If you want to manage more channels: ```php -$telegram->setCommandConfig('sendtochannel', ['your_channel'=>['@type_here_your_channel', '@type_here_another_channel', '@and_so_on']]); +$telegram->setCommandConfig('sendtochannel', ['your_channel' => ['@type_here_your_channel', '@type_here_another_channel', '@and_so_on']]); ``` - Enjoy! ### Upload and Download directory path -You can override the default Upload and Download directory with: +To use the Upload and Download functionality, you need to set the paths with: ```php -$telegram->setDownloadPath('yourpath/Download'); -$telegram->setUploadPath('yourpath/Upload'); +$telegram->setDownloadPath('/your/path/Download'); +$telegram->setUploadPath('/your/path/Upload'); ``` ## Documentation -Take a look at the repo [Wiki](https://github.com/php-telegram-bot/core/wiki) for further information and tutorials! +Take a look at the repo [Wiki][wiki] for further information and tutorials! Feel free to improve! ## Example bot We're busy working on a full A-Z example bot, to help get you started with this library and to show you how to use all its features. -You can check the progress of the [example bot repository](https://github.com/php-telegram-bot/example-bot). +You can check the progress of the [example bot repository][example-bot-repository]). ## Projects with this library Here's a list of projects that feats this library, feel free to add yours! -- [Super-Dice-Roll](https://github.com/RafaelDelboni/Super-Dice-Roll) [@superdiceroll_bot](https://telegram.me/superdiceroll_bot) +- [Inline Games](https://github.com/jacklul/inlinegamesbot) ([@inlinegamesbot](https://telegram.me/inlinegamesbot)) +- [Super-Dice-Roll](https://github.com/RafaelDelboni/Super-Dice-Roll) ([@superdiceroll_bot](https://telegram.me/superdiceroll_bot)) - [tg-mentioned-bot](https://github.com/gruessung/tg-mentioned-bot) ## Troubleshooting If you like living on the edge, please report any bugs you find on the -[PHP Telegram Bot issues](https://github.com/php-telegram-bot/core/issues) page. +[PHP Telegram Bot issues][issues] page. ## Contributing @@ -558,3 +581,22 @@ which this project is licensed under. ## Credits Credit list in [CREDITS](CREDITS) + +[Telegram-Bot-API]: https://core.telegram.org/bots/api "Telegram Bot API" +[composer]: https://getcomposer.org/ "Composer" +[example-bot-repository]: https://github.com/php-telegram-bot/example-bot "Example Bot repository" +[api-setwebhook]: https://core.telegram.org/bots/api#setwebhook "Webhook on Telegram Bot API" +[set.php]: https://github.com/php-telegram-bot/example-bot/blob/master/set.php "example set.php" +[unset.php]: https://github.com/php-telegram-bot/example-bot/blob/master/unset.php "example unset.php" +[hook.php]: https://github.com/php-telegram-bot/example-bot/blob/master/hook.php "example hook.php" +[getUpdatesCLI.php]: https://github.com/php-telegram-bot/example-bot/blob/master/getUpdatesCLI.php "example getUpdatesCLI.php" +[AdminCommands-folder]: https://github.com/php-telegram-bot/core/tree/master/src/Commands/AdminCommands "Admin commands folder" +[ExampleCommands-folder]: https://github.com/php-telegram-bot/example-bot/blob/master/Commands "Example commands folder" +[ImageCommand.php]: https://github.com/php-telegram-bot/example-bot/blob/master/Commands/ImageCommand.php "example /image command" +[WhoamiCommand.php]: https://github.com/php-telegram-bot/example-bot/blob/master/Commands/WhoamiCommand.php "example /whoami command" +[HelpCommand.php]: https://github.com/php-telegram-bot/example-bot/blob/master/Commands/HelpCommand.php "example /help command" +[SendtochannelCommand.php]: https://github.com/php-telegram-bot/core/blob/master/src/Commands/AdminCommands/SendtochannelCommand.php "/sendtochannel admin command" +[DB::selectChats]: https://github.com/php-telegram-bot/core/blob/0.46.0/src/DB.php#L1000 "DB::selectChats() parameters" +[wiki]: https://github.com/php-telegram-bot/core/wiki "PHP Telegram Bot Wiki" +[wiki-create-your-own-commands]: https://github.com/php-telegram-bot/core/wiki/Create-your-own-commands "Create your own commands" +[issues]: https://github.com/php-telegram-bot/core/issues "PHP Telegram Bot Issues"