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(11mo ago)75694.7k—0.7%117AGPL-3.0-onlyPHPCI passing

Since Feb 3Pushed 11mo 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 1mo 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

51

—

FairBetter than 96% of packages

Maintenance50

Moderate activity, may be stable

Popularity51

Moderate usage in the ecosystem

Community24

Small or concentrated contributor base

Maturity65

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

352d 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.4k855.0k18](/packages/danog-madelineproto)[php-ffmpeg/php-ffmpeg

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

5.0k21.7M165](/packages/php-ffmpeg-php-ffmpeg)[happyworm/jplayer

jPlayer allows you to create a media player with a consistent interface and experience across all browsers.

4.6k114.2k1](/packages/happyworm-jplayer)[askoldex/teletant

Telegram bot framework

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

PHP wrapper for FFmpeg application

495270.5k1](/packages/codescale-ffmpeg-php)[char0n/ffmpeg-php

PHP wrapper for FFmpeg application

495225.1k1](/packages/char0n-ffmpeg-php)

PHPackages © 2026

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