PHPackages                             danog/tg-file-decoder - 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. [Image & Media](/categories/media)
4. /
5. danog/tg-file-decoder

ActiveProject[Image & Media](/categories/media)

danog/tg-file-decoder
=====================

Decode Telegram bot API file IDs

1.0.2(1y ago)77766.8k—9.7%147AGPL-3.0-onlyPHPCI failing

Since Feb 3Pushed 1y ago9 watchersCompare

[ Source](https://github.com/danog/tg-file-decoder)[ Packagist](https://packagist.org/packages/danog/tg-file-decoder)[ GitHub Sponsors](https://github.com/danog)[ RSS](/packages/danog-tg-file-decoder/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (2)Dependencies (5)Versions (18)Used By (7)

tg-file-decoder
===============

[](#tg-file-decoder)

[![build](https://github.com/danog/tg-file-decoder/workflows/build/badge.svg)](https://github.com/danog/tg-file-decoder/workflows/build/badge.svg)[![Psalm coverage](https://camo.githubusercontent.com/1a53df8b6418bc09bb22f1fd518b816cf327598397fd614fe5aa19f9a607cc6a/68747470733a2f2f73686570686572642e6465762f6769746875622f64616e6f672f74672d66696c652d6465636f6465722f636f7665726167652e737667)](https://shepherd.dev/github/danog/tg-file-decoder)[![Psalm level 1](https://camo.githubusercontent.com/5d22b32abe640dc2f77614b62fae1e441e6263623e77836999fa7e0d4fe5c488/68747470733a2f2f73686570686572642e6465762f6769746875622f64616e6f672f74672d66696c652d6465636f6465722f6c6576656c2e737667)](https://shepherd.dev/github/danog/tg-file-decoder)

Decode and encode [Telegram bot API file IDs](https://core.telegram.org)!

This library was initially created for [MadelineProto](https://docs.madelineproto.xyz), an async PHP client API for the telegram MTProto protocol.

Install
-------

[](#install)

```
composer require danog/tg-file-decoder
```

Examples:
---------

[](#examples)

### Decoding bot API file IDs

[](#decoding-bot-api-file-ids)

```
use danog\Decoder\FileId;
use danog\Decoder\UniqueFileId;

$fileId = FileId::fromBotAPI('CAACAgQAAxkDAAJEsl44nl3yxPZ8biI8uhaA7rbQceOSAAKtAQACsTisUXvMEbVnTuQkGAQ');

$version = $fileId->version; // bot API file ID version, usually 4
$subVersion = $fileId->subVersion; // bot API file ID subversion, equivalent to a specific tdlib version

$dcId = $fileId->dcId; // On which datacenter is this file stored

$type = $fileId->type; // File type

$id = $fileId->id;
$accessHash = $fileId->accessHash;

$fileReference = $fileId->fileReference; // File reference, https://core.telegram.org/api/file_reference
$url = $fileId->url; // URL, file IDs with encoded webLocation

// You can also use hasFileReference and hasUrl
$fileIdReencoded = $fileId->getBotAPI(); // CAACAgQAAxkDAAJEsl44nl3yxPZ8biI8uhaA7rbQceOSAAKtAQACsTisUXvMEbVnTuQkGAQ
$fileIdReencoded = (string) $fileId;     // CAACAgQAAxkDAAJEsl44nl3yxPZ8biI8uhaA7rbQceOSAAKtAQACsTisUXvMEbVnTuQkGAQ

// For photos, thumbnails if ($fileId->getType() value)
$volumeId = $fileId->volumeId;
$localId = $fileId->localId;

$photoSizeSource = $fileId->photoSizeSource; // PhotoSizeSource object
$photoSizeSource->dialogId;
$photoSizeSource->stickerSetId;

// And more, depending on photosize source
```

The bot API subversion, present since file IDs v4, is equivalent to the [version of tdlib](https://github.com/tdlib/td/blob/master/td/telegram/Version.h#L13) used server-side in the bot API.

For file types, see [file types](#bot-api-file-id-types). For photosize source, see [here](#photosize-source).

### Decoding bot API unique file IDs

[](#decoding-bot-api-unique-file-ids)

```
$uniqueFileId = UniqueFileId::fromUniqueBotAPI('AgADrQEAArE4rFE');

$type = $fileId->type; // Unique file type

$id = $uniqueFileId->id;
$url = $uniqueFileId->url; // URL, for unique file IDs with encoded webLocation

// For photos
$volumeId = $uniqueFileId->volumeId;
$localId = $uniqueFileId->localId;
```

For unique file types, see [unique types](#bot-api-unique-file-id-types).

### Extracting unique file IDs from full file IDs

[](#extracting-unique-file-ids-from-full-file-ids)

```
$full = 'CAACAgQAAxkDAAJEsl44nl3yxPZ8biI8uhaA7rbQceOSAAKtAQACsTisUXvMEbVnTuQkGAQ';
$unique = 'AgADrQEAArE4rFE';

$fileId = FileId::fromBotAPI($full);
$uniqueFileId = UniqueFileId::fromUniqueBotAPI($unique);
$uniqueFileIdExtracted1 = UniqueFileId::fromBotAPI($full);

$uniqueFileIdExtracted2 = $fileId->getUniqueBotAPI();

var_dump(((string) $uniqueFileId) === ((string) $uniqueFileIdExtracted1)); // true, always AgADrQEAArE4rFE!
var_dump(((string) $uniqueFileId) === ((string) $uniqueFileIdExtracted2)); // true, always AgADrQEAArE4rFE!
```

### Photosize source

[](#photosize-source)

```
$fileId = FileId::fromString('CAACAgQAAxkDAAJEsl44nl3yxPZ8biI8uhaA7rbQceOSAAKtAQACsTisUXvMEbVnTuQkGAQ');

$photoSizeSource = $fileId->photoSizeSource; // PhotoSizeSource object

$sourceType = $photoSizeSource->type;

// If $sourceType === PHOTOSIZE_SOURCE_DIALOGPHOTO_SMALL|PHOTOSIZE_SOURCE_DIALOGPHOTO_SMALL or
// If $photoSizeSource instanceof PhotoSizeSourceDialogPhoto
$dialogId = $photoSizeSource->dialogId;
$dialogId = $photoSizeSource->sticketSetId;
```

The `PhotoSizeSource` abstract base class indicates the source of a specific photosize from a chat photo, photo, stickerset thumbnail, file thumbnail.

Click [here »](https://github.com/danog/tg-file-decoder/blob/master/docs/index.md) to view the full list of `PhotoSizeSource` types.

### Building custom file IDs

[](#building-custom-file-ids)

```
$fileId = new FileId(
    type: FileIdType::STICKER,
    id: $id,
    accessHash: $accessHash,
    // and so on...
);

$encoded = (string) $fileId; // CAACAgQAAxkDAAJEsl44nl3yxPZ8biI8uhaA7rbQceOSAAKtAQACsTisUXvMEbVnTuQkGAQ, or something
```

### Bot API file ID types

[](#bot-api-file-id-types)

The file type is a PHP enum indicating the type of file, [danog\\Decoder\\FileIdType](https://github.com/danog/tg-file-decoder/blob/master/docs/danog/Decoder/FileIdType.md).

Click [here »](https://github.com/danog/tg-file-decoder/blob/master/docs/danog/Decoder/FileIdType.md) to view the full list of file ID types.

The enum also offers a `FileIdType::from` method that can be used to obtain the correct case, from a string version of the file type, typically the one used in bot API file objects.

### Bot API unique file ID types

[](#bot-api-unique-file-id-types)

The unique file type is a PHP enum uniquely indicating the unique file, [danog\\Decoder\\UniqueFileIdType](https://github.com/danog/tg-file-decoder/blob/master/docs/danog/Decoder/UniqueFileIdType.md).

Click [here »](https://github.com/danog/tg-file-decoder/blob/master/docs/danog/Decoder/UniqueFileIdType.md) to view the full list of file ID types.

Full API documentation
----------------------

[](#full-api-documentation)

Click [here »](https://github.com/danog/tg-file-decoder/blob/master/docs/index.md) to view the full API documentation.

###  Health Score

50

—

FairBetter than 95% of packages

Maintenance44

Moderate activity, may be stable

Popularity53

Moderate usage in the ecosystem

Community24

Small or concentrated contributor base

Maturity66

Established project with proven stability

 Bus Factor1

Top contributor holds 98.6% 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 ~121 days

Recently: every ~231 days

Total

17

Last Release

443d ago

Major Versions

0.1.13 → 1.0.02024-04-01

PHP version history (2 changes)0.1.0PHP >=7.0

0.1.12PHP >=8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/e1586cd637028e4f8da85f2252b8f4b81e05f6b17a93f92c34ff064dd838e6bb?d=identicon)[danog](/maintainers/danog)

---

Top Contributors

[![danog](https://avatars.githubusercontent.com/u/7339644?v=4)](https://github.com/danog "danog (72 commits)")[![arisudesu](https://avatars.githubusercontent.com/u/6342849?v=4)](https://github.com/arisudesu "arisudesu (1 commits)")

---

Tags

bot-apidecoderfilesphotostelegramtelegram-bot-apiaudiovideofilestelegrambot apimtprotostickersfile ID

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Type Coverage Yes

### Embed Badge

![Health badge](/badges/danog-tg-file-decoder/health.svg)

```
[![Health](https://phpackages.com/badges/danog-tg-file-decoder/health.svg)](https://phpackages.com/packages/danog-tg-file-decoder)
```

###  Alternatives

[danog/madelineproto

Async PHP client API for the telegram MTProto protocol.

3.5k920.5k24](/packages/danog-madelineproto)[php-ffmpeg/php-ffmpeg

FFMpeg PHP, an Object Oriented library to communicate with AVconv / ffmpeg

5.0k24.8M211](/packages/php-ffmpeg-php-ffmpeg)[askoldex/teletant

Telegram bot framework

221.0k](/packages/askoldex-teletant)[codescale/ffmpeg-php

PHP wrapper for FFmpeg application

493277.3k2](/packages/codescale-ffmpeg-php)[char0n/ffmpeg-php

PHP wrapper for FFmpeg application

493244.9k1](/packages/char0n-ffmpeg-php)[dereuromark/media-embed

A PHP library to deal with all those media services around, parsing their URLs and embedding their audio/video content in websites.

180591.1k20](/packages/dereuromark-media-embed)

PHPackages © 2026

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