From a226f30f7c8d21fe3e9e8a1d5c38158218af5e53 Mon Sep 17 00:00:00 2001 From: CrazyTapok Date: Sat, 22 Jul 2023 19:45:30 +0300 Subject: [PATCH] Update README --- README.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 60 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index a36ecee..d5a5908 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,9 @@ composer require tg/tgwebvalid --no-dev With the `--no-dev` flag, only the dependencies needed to run your project in a production environment will be installed. ## Using -The first thing you need to do is set the token of the telegram bot on behalf of which the authentication is performed in the constructor of the TgWebValid class. And store the result in a variable +The first thing you need to do is to set in the constructor of the TgWebValid class the token of the Telegram bot on behalf of which authentication is performed by default. And store the result in a variable. + +Also, if you want to throw an exception in case of a validation error, set the second parameter to true. But be sure to use the `try catch` structure ```php addBot(new BotConfig('secondary' 'TELEGRAM_BOT_TOKEN_2')); +$tgWebValid->addBot(new BotConfig('minor' 'TELEGRAM_BOT_TOKEN_3')); +``` + +Getting a bot to work is easy. Specify the name of the bot to work with, or leave the argument empty to get the default bot + +```php +$bot = $tgWebValid->bot('minor'); +``` Next, you need to decide on the type of authentication you need to do. * Web App Authentication [Example](#telegram-web-app-authentication) * Login Widget Authentication [Example](#telegram-login-widget-authentication) ## Telegram Web App authentication -To perform this type of verification, you should use the `validateInitData` method. Which argument accepts data for processing. If the validation is successful, you will be returned an `InitData` object with the data, or `false` if the validation fails +To perform this type of verification, you should use the `validateInitData` method. Which argument accepts data for processing. If the validation is successful, you will be returned an `InitData` object with the data, or `false` if the validation fails. +Use the second argument to enable or disable an exception on failed validation ```php -$initData = $tgWebValid->validateInitData('query_id=...'); +$initData = $bot->validateInitData('query_id=...'); if (!$initData) { // validation fails @@ -56,7 +75,7 @@ if (!$initData) { * The initData object can contain the following data: */ -// Unix time opening a web application +// Time opening a web application $initData->authDate; // An object containing data about the current user @@ -74,8 +93,10 @@ $initData->chat; ## Telegram Login Widget authentication To perform this type of check, you should use the `validateLoginWidget` method. Which argument accepts an array with raw user data. You will be returned a `LoginWidget` object with the data, or `false` if the validation fails + +Use the second argument to enable or disable an exception on failed validation ```php -$loginWidget = $tgWebValid->validateLoginWidget([ +$loginWidget = $bot->validateLoginWidget([ 'auth_date' => 1679130118, 'first_name' => 'Сергій', // other fields @@ -101,7 +122,7 @@ $loginWidget->username; // Link to profile photo $loginWidget->photoUrl; -// Unix authorization time +// Authorization time $loginWidget->authDate; // and other data @@ -109,6 +130,38 @@ $loginWidget->authDate; ``` `Note`. Certain data is present depending on the situation, so sometimes it can be `null` instead of data or a data object. +## Full example + +```php +addBot(new BotConfig('secondary' 'TELEGRAM_BOT_TOKEN_2')); + $tgWebValid->addBot(new BotConfig('minor' 'TELEGRAM_BOT_TOKEN_3')); + + $initData = $tgWebValid->bot()->validateInitData('query_id=...'); + + var_dump($initData); + +} catch (ValidationException $e) { + // Verification failed +} catch (BotException $e) { + // The bot name is incorrect +} catch (Exception $e) { + // Other exceptions +} +``` ## Additionally Our library is autonomous, so it can be used in any frameworks, or without them.