PHPackages                             kilogram/auth - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. kilogram/auth

ActiveLibrary[Authentication & Authorization](/categories/authentication)

kilogram/auth
=============

Secure and simple validation library for Telegram Login Widget and Web App data (including Third-Party validation support).

1.0.1(7mo ago)01MITPHPPHP ^8.2CI passing

Since Dec 25Pushed 1mo agoCompare

[ Source](https://github.com/chipslays/telegram-auth)[ Packagist](https://packagist.org/packages/kilogram/auth)[ RSS](/packages/kilogram-auth/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (2)Dependencies (1)Versions (3)Used By (0)

 Telegram Auth 🔑
=================

[](#----telegram-auth-)

 [![Latest Version](https://camo.githubusercontent.com/df21a96b132e1b807665288da825670608f40943685815586e1a2116f93cd514/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6b696c6f6772616d2f61757468)](https://packagist.org/packages/kilogram/auth) [![PHP Version](https://camo.githubusercontent.com/c2c1ea416554cbc7f7ee95bb1c63c17d0a9583812fceee98c42f6bcdfad8ee4a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6b696c6f6772616d2f61757468)](https://packagist.org/packages/kilogram/auth) [![License](https://camo.githubusercontent.com/6a2c2bbfab9414ebc0caa7b28a1c82aa30dd5312eeefb0826b4918955ce1cef3/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f63686970736c6179732f74656c656772616d2d617574683f31)](https://github.com/chipslays/telegram-auth/blob/main/LICENSE) [![Stars](https://camo.githubusercontent.com/71ece66aba25ed22d55be5db4345d1cfa79c11487f5def3cf2f275f8a3daf4dd/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f63686970736c6179732f74656c656772616d2d617574683f7374796c653d736f6369616c)](https://github.com/chipslays/telegram-auth) [![Downloads](https://camo.githubusercontent.com/d90a5fe9aede16c5d0ce97c4cc9c13511d69d6174cf63be8b7fe329bcc13de9a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6b696c6f6772616d2f61757468)](https://packagist.org/packages/kilogram/auth)

 Secure and simple validation library for Telegram **[Login Widget](https://core.telegram.org/widgets/login)** and **[Web App](https://core.telegram.org/bots/webapps)** (including **[Third-Party](https://core.telegram.org/bots/webapps#validating-data-for-third-party-use)** validation support). Features
--------

[](#features)

- ✅ **Telegram Login Widget** – validate payloads from the login widget (hash verification, timestamp check).
- ✅ **Telegram Web App** – authenticate users inside mini‑apps by verifying `initData`.
- ✅ **Third‑Party Use** – validate Telegram data for external services (without a bot token, using bot ID).
- ✅ **Simple API** – ready‑to‑use methods like `isValidLoginWidget()`, `validateWebApp()`, plus exceptions for error handling.
- ✅ **Secure by design** – uses cryptographically strong hashing (`hash_hmac`, `sodium`) to prevent data tampering.
- ✅ **PHP 8.2+** – modern, strictly typed code.

Requirements
------------

[](#requirements)

- [PHP](https://www.php.net/): `^8.2`
- [ext-hash](https://www.php.net/manual/en/book.hash.php): `*`
- [ext-sodium](https://www.php.net/manual/en/book.sodium.php): `*`

Installation
------------

[](#installation)

```
composer require kilogram/auth
```

Quick start
-----------

[](#quick-start)

Note

Usage examples are also available in the [examples](/examples) directory.

### Login Widget (simple)

[](#login-widget-simple)

Basic validation of the data received from the Telegram Login Widget. Checks the hash and timestamp, returns a boolean result.

```
use Kilogram\Auth\Validator;

$data = $_GET;

$validator = new Validator($_ENV['TELEGRAM_BOT_TOKEN']);

if ($validator->isValidLoginWidget($data)) {
    echo "Authenticated. User ID: " . $data['id'];
} else {
    echo "Authentication failed";
}
```

### Login Widget (with exceptions)

[](#login-widget-with-exceptions)

A more robust approach that throws specific exceptions for invalid input (missing parameters) and validation failures (tampered data).

```
use Kilogram\Auth\Validator;
use Kilogram\Auth\Exceptions\InvalidDataException;
use Kilogram\Auth\Exceptions\ValidationException;

$data = $_GET;

$validator = new Validator($_ENV['TELEGRAM_BOT_TOKEN']);

try {
    $validator->validateLoginWidget($data);
    echo "Authenticated. Hello " . ($data['first_name'] ?? 'user');
} catch (InvalidDataException $e) {
    // Developer error: invalid input format (e.g. missing "hash")
    echo "Bad request: " . $e->getMessage();
} catch (ValidationException $e) {
    // Invalid signature: possible tampering
    echo "Authentication failed";
}
```

### Web App (simple)

[](#web-app-simple)

Verifies the `initData` string from a Telegram Web App. Returns `true` if the signature is valid and the data is fresh.

```
use Kilogram\Auth\Validator;

$initData = $_POST['initData'];

$validator = new Validator($_ENV['TELEGRAM_BOT_TOKEN']);

if ($validator->isValidWebApp($initData)) {
    echo "Web App authenticated";
} else {
    echo "Invalid initData";
}
```

### Web App (with exceptions)

[](#web-app-with-exceptions)

Same as above, but throws exceptions for malformed input or invalid signatures, giving you finer control over error handling.

```
use Kilogram\Auth\Validator;
use Kilogram\Auth\Exceptions\InvalidDataException;
use Kilogram\Auth\Exceptions\ValidationException;

$initData = $_POST['initData'];

$validator = new Validator($_ENV['TELEGRAM_BOT_TOKEN']);

try {
    $validator->validateWebApp($initData);
    echo "Web App authenticated";
} catch (InvalidDataException $e) {
    // Developer error: initData format is broken / empty
    echo "Bad request: " . $e->getMessage();
} catch (ValidationException $e) {
    // Invalid signature
    echo "Authentication failed";
}
```

### Web App Third-Party (simple)

[](#web-app-third-party-simple)

Validates data for third‑party services without using a bot token. Only the bot ID is required.

```
use Kilogram\Auth\Validator;

$initData = $_POST['initData'];

if (Validator::isValidWebAppDataForThirdParty($initData, $botId)) {
    echo "Web App authenticated (Third-Party)!";
} else {
    echo "Invalid data";
}
```

### Web App Third-Party (with exceptions)

[](#web-app-third-party-with-exceptions)

The same third‑party validation, but with exception-based error reporting.

```
use Kilogram\Auth\Validator;
use Kilogram\Auth\Exceptions\ValidationException;

$initData = $_POST['initData'];

try {
    Validator::validateWebAppDataForThirdParty($initData, $botId);
    echo "Web App authorized!";
} catch (ValidationException $e) {
    echo "Authentication failed";
}
```

Tip

**When to use simple vs exceptions?**
Use the **simple** methods (`isValid*`) when you only need a boolean result (e.g., in controllers, middleware, or conditional logic).
Use the **exception** methods (`validate*`) when you need granular error handling – they distinguish between **malformed input** (developer errors, e.g., missing parameters) and **invalid signatures** (security issues, e.g., tampered data).

License
-------

[](#license)

MIT

###  Health Score

35

—

LowBetter than 77% of packages

Maintenance78

Regular maintenance activity

Popularity1

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

236d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/19103498?v=4)[chipslays](/maintainers/chipslays)[@chipslays](https://github.com/chipslays)

---

Top Contributors

[![chipslays](https://avatars.githubusercontent.com/u/19103498?v=4)](https://github.com/chipslays "chipslays (11 commits)")

---

Tags

validationsecurityauthAuthenticationbottelegramwebapplogin-widget

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/kilogram-auth/health.svg)

```
[![Health](https://phpackages.com/badges/kilogram-auth/health.svg)](https://phpackages.com/packages/kilogram-auth)
```

###  Alternatives

[tg/tgwebvalid

An easy way to validate Telegram Login Widget and Telegram Mini App users on your website using PHP

6827.5k1](/packages/tg-tgwebvalid)[delight-im/auth

Authentication for PHP. Simple, lightweight and secure.

1.2k156.5k37](/packages/delight-im-auth)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)