021/telegram-validation

A library for validating Telegram callbacks

v5.0.1 2024-04-12 11:48 UTC

Requires

• php: ^8.1|^8.2|^8.3
• 021/api-entity: ^2.0.1

Requires (Dev)

• phpunit/phpunit: ^10.5

MIT

• Сергій Засадинський
• 021

• authorization
• Authentication
• validation
• login
• auth
• verification
• webapp
• telegram

README

This library helps verify callbacks from Telegram.

Installation

Install via Composer:

composer require 021/telegram-validation

Using

Validation

Web App Init Data

Mechanism: Validating data received via the Mini App

$token = 'YOUR_BOT_TOKEN';

// Short with helper function
use function Telegram\Validation\Helpers\validate_wa_init_data;

$isValid = validate_wa_init_data('query_id=...', $token);

// Expanded with class
use Telegram\Validation\WebAppInitData;

$validator = new WebAppInitData($token);
$isValid = $validator->validate('query_id=...');

Login Widget

Mechanism: Checking authorization

$token = 'YOUR_BOT_TOKEN';
$input = ['auth_date' => 666, /*...*/]; // request input

// Short with helper function
use function Telegram\Validation\Helpers\validate_login_widget;

$isValid = validate_login_widget($input, $token);

// Expanded with class
use Telegram\Validation\LoginWidget;

$validator = new LoginWidget($token);
$isValid = $validator->validate($input);

Parsing

021/telegram-validation also provides classes to parse the data to objects.

Web App Init Data

$token = 'YOUR_BOT_TOKEN';
/** 
 * @link https://core.telegram.org/bots/webapps#webappinitdata
 * @var \Telegram\Validation\Entities\WebAppInitData $webAppInitData 
 */
$webAppInitData;

// Short with helper function
use function Telegram\Validation\Helpers\parse_wa_init_data;

$webAppInitData = parse_wa_init_data('query_id=...', $token);

// Expanded with class
use Telegram\Validation\WebAppInitData;

$validator = new WebAppInitData($token);
$webAppInitData = $validator->extract('query_id=...');

// Accessing fields
echo $webAppInitData->queryId; // query_id
echo $webAppInitData->chat->username; // chat.username
echo $webAppInitData->chatType; // chat_type
// ... any other fields

Login Widget

$token = 'YOUR_BOT_TOKEN';
$input = ['auth_date' => 666, /*...*/]; // request input 
/** 
 * @link https://core.telegram.org/widgets/login#receiving-authorization-data
 * @var \Telegram\Validation\Entities\LoginWidgetCallback $loginWidget 
 */
$loginWidget;

// Short with helper function
use function Telegram\Validation\Helpers\parse_login_widget;
$loginWidget = parse_login_widget($input, $token);

// Expanded with class
use Telegram\Validation\LoginWidget;

$validator = new LoginWidget($token);
$loginWidget = $validator->extract($input);

// Accessing fields
echo $loginWidget->firstName; // first_name
echo $loginWidget->lastName; // last_name
/** @var \Carbon\CarbonInterface $carbon */
$carbon = $loginWidget->authDate; // auth_date

Security

If you discover a security vulnerability in 021/telegram-validation, 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

021/telegram-validation - is open source software available under the MIT. See the license file for more information.