README.md

Library for Telegram Web App User Validation and Telegram Login Widget for PHP

About TgWebValid

They say we are cool 😎

⭐️ Support us, give us a star on GitHub and become our sponsor 😊

🙏 Please let us know on GitHub if something isn't working for you or if you need additional functionality

---

User authentication occurs by encrypting the received, raw, user data and comparing it with the hash provided by the telegram. A failed check can be equated with a possible attempt to bypass or hack the system.

The library verifies users Telegram Login Widget and Telegram Web App

WARNING: Use user data only after successful authentication

To quickly and safely verify a user, we recommend following a few simple steps

Installation

You can install the TgWebValid library through the composer package manager by executing the command

composer require tg/tgwebvalid

Add the --no-dev flag to install only the dependencies needed to run your project in a production environment.

Using

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

use TgWebValid\TgWebValid;

include './vendor/autoload.php';

$tgWebValid = new TgWebValid('TELEGRAM_BOT_TOKEN', false);

If your project uses multiple bots, you can easily interact with them, just add them all

<?php

$tgWebValid->addBot('secondary', 'TELEGRAM_BOT_TOKEN_2');
$tgWebValid->addBot('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

$bot = $tgWebValid->bot('minor');

Next, you need to decide on the type of authentication you need to do.

• Web App Authentication Example
• Login Widget Authentication Example

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.

Use the second argument to enable or disable an exception on failed validation

$initData = $bot->validateInitData('query_id=...');

if (!$initData) {
    // validation fails
}

/**
 * The initData object can contain the following data:
 */

// Time opening a web application
$initData->authDate;

// An object containing data about the current user
$initData->user;

// May contain a chat partner data object
$initData->receiver;

// May contain an object with chat data
$initData->chat;

// and other data

Note. Certain data is present depending on the situation, so sometimes it can be null instead of data or a data object. More details in the Telegram official documentation

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

$loginWidget = $bot->validateLoginWidget([
    'auth_date' => 1679130118,
    'first_name' => 'Сергій',
    // other fields
]);

if (!$loginWidget) {
    // validation fails
}

/**
 * The LoginWidget object can contain the following data:
 */

// User token
$loginWidget->id;

// User first name
$loginWidget->firstName;

// Username
$loginWidget->username;

// Link to profile photo
$loginWidget->photoUrl;

// Authorization time
$loginWidget->authDate;

// and other data

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

use TgWebValid\TgWebValid;
use TgWebValid\Exceptions\BotException;
use TgWebValid\Exceptions\ValidationException;
use Exception;

include './vendor/autoload.php';

try {
    $tgWebValid = new TgWebValid('TELEGRAM_BOT_TOKEN', true);

    // Add bots only when needed
    $tgWebValid->addBot('secondary', 'TELEGRAM_BOT_TOKEN_2');
    $tgWebValid->addBot('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.

Security

If you discover a security vulnerability in TgWebValid, please create an issue with a detailed description. All security vulnerabilities will be fixed immediately. Pull requests are also welcome.

Assistance

We will be glad if you join the development and improvement of the project. You can create an issue and/or a pull request

License

TgWebValid - is open source software available under the MIT. See the license file for more information.