tg-file-decoder

Decode Telegram bot API file IDs.

Install

composer require danog/tg-file-decoder

On 32-bit systems, phpseclib is also required.

Examples:

Decoding bot API file IDs

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

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

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

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

$type = $fileId->getType(); // File type
$typeName = $fileId->getTypeName(); // File type (as string)

$id = $fileId->getId();
$accessHash = $fileId->getAccessHash();

$fileReference = $fileId->getFileReference(); // File reference, https://core.telegram.org/api/file_reference
$url = $fileId->getUrl(); // 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() <= PHOTO)
$volumeId = $fileId->getVolumeID();
$localId = $fileId->getLocalID();

// if $fileId->hasPhotoSizeSource()
$photoSizeSource = $fileId->getPhotoSizeSource(); // PhotoSizeSource object
$photoSizeSource->getDialogId();
$photoSizeSource->getStickerSetId();

// And more, depending on photosize source

The bot API subversion, present since file IDs v4, is equivalent to the version of tdlib used server-side in the bot API.

For file types, see file types. For photosize source, see here.

Decoding bot API unique file IDs

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

$type = $fileId->getType(); // Unique file type
$typeName = $fileId->getTypeName(); // Unique file type (as string)

$id = $uniqueFileId->getId();
$accessHash = $uniqueFileId->getAccessHash();
$url = $uniqueFileId->getUrl(); // URL, for unique file IDs with encoded webLocation
// You can also use hasUrl

// For photos
$volumeId = $uniqueFileId->getVolumeID();
$localId = $uniqueFileId->getLocalID();

For unique file types, see unique types.

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

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

$photoSizeSource = $fileId->getPhotoSizeSource(); // PhotoSizeSource object

$sourceType = $photoSizeSource->getType();

// If $sourceType === PHOTOSIZE_SOURCE_DIALOGPHOTO_SMALL|PHOTOSIZE_SOURCE_DIALOGPHOTO_SMALL or 
// If $photoSizeSource instanceof PhotoSizeSourceDialogPhoto
$dialogId = $photoSizeSource->getDialogId();
$dialogId = $photoSizeSource->getStickerSetId();

The PhotoSizeSource abstract base class indicates the source of a specific photosize from a chat photo, photo, stickerset thumbnail, file thumbnail. Each photosize type (getType) is mapped to a specific subclass of the PhotoSizeSource abstract class, returned when calling getPhotoSizeSource. The photosize type is one of:

• const PHOTOSIZE_SOURCE_LEGACY = 0 - Legacy, used for file IDs with the deprecated secret field, returns PhotoSizeSourceLegacy class.
• const PHOTOSIZE_SOURCE_THUMBNAIL = 1 - Used for document and photo thumbnail, returns PhotoSizeSourceThumbnail class.
• const PHOTOSIZE_SOURCE_DIALOGPHOTO_SMALL = 2 - Used for dialog photos, returns PhotoSizeSourceDialogPhoto class.
• const PHOTOSIZE_SOURCE_DIALOGPHOTO_BIG = 3 - Used for dialog photos, returns PhotoSizeSourceDialogPhoto class.
• const PHOTOSIZE_SOURCE_STICKERSET_THUMBNAIL = 4 - Used for document and photo thumbnails, returns PhotoSizeSourceThumbnail class.

Building custom file IDs

$fileId = new FileId;

$fileId->setType(STICKER);
$fileId->setId($id);
$fileId->setAccessHash($customHash);

// You get it...

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

All classes, from FileId, to UniqueFileID, to PhotoSizeSource can be built using set methods for each and every field.

Bot API file ID types

The file type is a numeric constant indicating the type of file, (the constant is always in the danog\Decoder namespace). The file type name is a string version of the file type, typically the one used in bot API file objects.

The TYPES array contains a file type => file type name map. The TYPES_IDS array contains a file type name => file type map.

const CONSTANTNAME = value - Description (type name)

• const THUMBNAIL = 0 - Thumbnail (thumbnail)
• const PROFILE_PHOTO = 1 - Profile photo; used for users, supergroups and channels, chat photos are normal PHOTOs (profile_photo)
• const PHOTO = 2 - Photo (photo)
• const VOICE = 3 - Voice message (voice)
• const VIDEO = 4 - Video (video)
• const DOCUMENT = 5 - Document (document)
• const ENCRYPTED = 6 - Secret chat document (encrypted)
• const TEMP = 7 - Temp document (temp)
• const STICKER = 8 - Sticker (sticker)
• const AUDIO = 9 - Music (audio)
• const ANIMATION = 10 - GIF (animation)
• const ENCRYPTED_THUMBNAIL = 11 - Thumbnail of secret chat document (encrypted_thumbnail)
• const WALLPAPER = 12 - Wallpaper (wallpaper)
• const VIDEO_NOTE = 13 - Round video (video_note)
• const SECURE_RAW = 14 - Passport raw file (secure_raw)
• const SECURE = 15 - Passport file (secure)
• const WALLPAPER = 16 - Background (background)
• const WALLPAPER = 17 - Size (size)
• const NONE = 18 -

Bot API unique file ID types

The unique file type is a numeric constant indicating the type of the unique file ID, (the constant is always in the danog\Decoder namespace). The unique file type name is a string version of the unique file type, typically the one used in bot API file objects.

The UNIQUE_TYPES array contains a unique file type => unique file type name map. The UNIQUE_TYPES_IDS array contains a unique file type name => unique file type map. The FULL_UNIQUE_MAP array contains a full file type => unique file type map.

• const UNIQUE_WEB = 0 - Used for web files (all file types that have a URL (hasUrl))
• const UNIQUE_PHOTO = 1 - Used for photos and similar (getType() <= PHOTO)
• const UNIQUE_DOCUMENT = 2 - Used for all other types of files (documents, audio, video, voice, sticker, animation, video note)
• const UNIQUE_SECURE = 3 - Used for passport files
• const UNIQUE_ENCRYPTED = 4 - Used for secret chat files
• const UNIQUE_TEMP = 5 - Used for temp files

Full API documentation

• FileId - Main file ID class
  • fromBotAPI
  • getBotAPI
  • getUnique
  • getVersion
  • setVersion
  • getSubVersion
  • setSubVersion
  • getType
  • getTypeName
  • setType
  • getFileReference
  • setFileReference
  • hasFileReference
  • getUrl
  • hasUrl
  • setUrl
  • getId
  • setId
  • hasId
  • getAccessHash
  • setAccessHash
  • getVolumeId
  • setVolumeId
  • hasVolumeId
  • getLocalId
  • setLocalId
  • hasLocalId
  • getPhotoSizeSource
  • setPhotoSizeSource
  • hasPhotoSizeSource
  • getDcId
  • setDcId
• PhotoSizeSourceDialogPhoto
  • setType
  • getDialogId
  • setDialogId
  • getDialogAccessHash
  • setDialogAccessHash
  • isSmallDialogPhoto
  • setDialogPhotoSmall
• PhotoSizeSourceLegacy
  • setType
  • getSecret
  • setSecret
• PhotoSizeSourceStickersetThumbnail
  • setType
  • getStickerSetId
  • setStickerSetId
  • getStickerSetAccessHash
  • setStickerSetAccessHash
• PhotoSizeSourceThumbnail
  • setType
  • getThumbFileType
  • getThumbFileTypeString
  • setThumbFileType
  • getThumbType
  • setThumbType
• UniqueFileId
  • __toString
  • getUniqueBotAPI
  • fromUniqueBotAPI
  • fromBotAPI
  • fromFileId
  • getTypeName
  • getType
  • setType
  • getId
  • setId
  • hasId
  • getVolumeId
  • setVolumeId
  • hasVolumeId
  • getLocalId
  • setLocalId
  • hasLocalId
  • getUrl
  • setUrl
  • hasUrl

FileId

Represents decoded bot API file ID.

• Full name: \danog\Decoder\FileId

fromBotAPI

Decode file ID from bot API file ID.

FileId::fromBotAPI( string $fileId ): self

• This method is static. Parameters:

Parameter	Type	Description
$fileId	string	File ID

---

getBotAPI

Get bot API file ID.

FileId::getBotAPI(  ): string

---

getUnique

Get unique file ID from file ID.

FileId::getUnique(  ): \danog\Decoder\UniqueFileId

---

__toString

Get bot API file ID.

FileId::__toString(  ): string

---

getVersion

Get bot API file ID version.

FileId::getVersion(  ): integer

---

setVersion

Set bot API file ID version.

FileId::setVersion( integer $_version ): self

Parameters:

Parameter	Type	Description
$_version	integer	Bot API file ID version.

---

getSubVersion

Get bot API file ID subversion.

FileId::getSubVersion(  ): integer

---

setSubVersion

Set bot API file ID subversion.

FileId::setSubVersion( integer $_subVersion ): self

Parameters:

Parameter	Type	Description
$_subVersion	integer	Bot API file ID subversion.

---

getType

Get file type.

FileId::getType(  ): integer

---

getTypeName

Get file type as string.

FileId::getTypeName(  ): string

---

setType

Set file type.

FileId::setType( integer $_type ): self

Parameters:

Parameter	Type	Description
$_type	integer	File type.

---

getFileReference

Get file reference.

FileId::getFileReference(  ): string

---

setFileReference

Set file reference.

FileId::setFileReference( string $_fileReference ): self

Parameters:

Parameter	Type	Description
$_fileReference	string	File reference.

---

hasFileReference

Check if has file reference.

FileId::hasFileReference(  ): boolean

---

getUrl

Get file URL for weblocation.

FileId::getUrl(  ): string

---

hasUrl

Check if has file URL.

FileId::hasUrl(  ): boolean

---

setUrl

Set file URL for weblocation.

FileId::setUrl( string $_url ): self

Parameters:

Parameter	Type	Description
$_url	string	File URL for weblocation.

---

getId

Get file id.

FileId::getId(  ): integer

---

setId

Set file id.

FileId::setId( integer $_id ): self

Parameters:

Parameter	Type	Description
$_id	integer	File id.

---

hasId

Check if has file id.

FileId::hasId(  ): boolean

---

getAccessHash

Get file access hash.

FileId::getAccessHash(  ): integer

---

setAccessHash

Set file access hash.

FileId::setAccessHash( integer $_accessHash ): self

Parameters:

Parameter	Type	Description
$_accessHash	integer	File access hash.

---

getVolumeId

Get photo volume ID.

FileId::getVolumeId(  ): integer

---

setVolumeId

Set photo volume ID.

FileId::setVolumeId( integer $_volumeId ): self

Parameters:

Parameter	Type	Description
$_volumeId	integer	Photo volume ID.

---

hasVolumeId

Check if has volume ID.

FileId::hasVolumeId(  ): boolean

---

getLocalId

Get photo local ID.

FileId::getLocalId(  ): integer

---

setLocalId

Set photo local ID.

FileId::setLocalId( integer $_localId ): self

Parameters:

Parameter	Type	Description
$_localId	integer	Photo local ID.

---

hasLocalId

Check if has local ID.

FileId::hasLocalId(  ): boolean

---

getPhotoSizeSource

Get photo size source.

FileId::getPhotoSizeSource(  ): \danog\Decoder\PhotoSizeSource

---

setPhotoSizeSource

Set photo size source.

FileId::setPhotoSizeSource( \danog\Decoder\PhotoSizeSource $_photoSizeSource ): self

Parameters:

Parameter	Type	Description
$_photoSizeSource	\danog\Decoder\PhotoSizeSource	Photo size source.

---

hasPhotoSizeSource

Check if has photo size source.

FileId::hasPhotoSizeSource(  ): boolean

---

getDcId

Get dC ID.

FileId::getDcId(  ): integer

---

setDcId

Set dC ID.

FileId::setDcId( integer $_dcId ): self

Parameters:

Parameter	Type	Description
$_dcId	integer	DC ID.

---

PhotoSizeSourceDialogPhoto

Represents source of photosize.

• Full name: \danog\Decoder\PhotoSizeSource\PhotoSizeSourceDialogPhoto
• Parent class: \danog\Decoder\PhotoSizeSource

setType

Get photosize source type.

PhotoSizeSourceDialogPhoto::setType( integer $type ): self

Parameters:

Parameter	Type	Description
$type	integer	Type

---

getDialogId

Get dialog ID.

PhotoSizeSourceDialogPhoto::getDialogId(  ): integer

---

setDialogId

Set dialog ID.

PhotoSizeSourceDialogPhoto::setDialogId( integer $id ): self

Parameters:

Parameter	Type	Description
$id	integer	Dialog ID

---

getDialogAccessHash

Get access hash of dialog.

PhotoSizeSourceDialogPhoto::getDialogAccessHash(  ): integer

---

setDialogAccessHash

Set access hash of dialog.

PhotoSizeSourceDialogPhoto::setDialogAccessHash( integer $dialogAccessHash ): self

Parameters:

Parameter	Type	Description
$dialogAccessHash	integer	Access hash of dialog

---

isSmallDialogPhoto

Get whether the big or small version of the photo is being used.

PhotoSizeSourceDialogPhoto::isSmallDialogPhoto(  ): boolean

---

setDialogPhotoSmall

Set whether the big or small version of the photo is being used.

PhotoSizeSourceDialogPhoto::setDialogPhotoSmall( boolean $_dialogPhotoSmall ): self

Parameters:

Parameter	Type	Description
$_dialogPhotoSmall	boolean	Whether the big or small version of the photo is being used

---

PhotoSizeSourceLegacy

Represents source of photosize.

• Full name: \danog\Decoder\PhotoSizeSource\PhotoSizeSourceLegacy
• Parent class: \danog\Decoder\PhotoSizeSource

setType

Get photosize source type.

PhotoSizeSourceLegacy::setType( integer $type ): self

Parameters:

Parameter	Type	Description
$type	integer	Type

---

getSecret

Get secret legacy ID.

PhotoSizeSourceLegacy::getSecret(  ): integer

---

setSecret

Set secret legacy ID.

PhotoSizeSourceLegacy::setSecret( integer $_secret ): self

Parameters:

Parameter	Type	Description
$_secret	integer	Secret legacy ID

---

PhotoSizeSourceStickersetThumbnail

Represents source of photosize.

• Full name: \danog\Decoder\PhotoSizeSource\PhotoSizeSourceStickersetThumbnail
• Parent class: \danog\Decoder\PhotoSizeSource

setType

Get photosize source type.

PhotoSizeSourceStickersetThumbnail::setType( integer $type ): self

Parameters:

Parameter	Type	Description
$type	integer	Type

---

getStickerSetId

Get stickerset ID.

PhotoSizeSourceStickersetThumbnail::getStickerSetId(  ): integer

---

setStickerSetId

Set stickerset ID.

PhotoSizeSourceStickersetThumbnail::setStickerSetId( integer $_stickerSetId ): self

Parameters:

Parameter	Type	Description
$_stickerSetId	integer	Stickerset ID

---

getStickerSetAccessHash

Get stickerset access hash.

PhotoSizeSourceStickersetThumbnail::getStickerSetAccessHash(  ): integer

---

setStickerSetAccessHash

Set stickerset access hash.

PhotoSizeSourceStickersetThumbnail::setStickerSetAccessHash( integer $_stickerSetAccessHash ): self

Parameters:

Parameter	Type	Description
$_stickerSetAccessHash	integer	Stickerset access hash

---

PhotoSizeSourceThumbnail

Represents source of photosize.

• Full name: \danog\Decoder\PhotoSizeSource\PhotoSizeSourceThumbnail
• Parent class: \danog\Decoder\PhotoSizeSource

setType

Get photosize source type.

PhotoSizeSourceThumbnail::setType( integer $type ): self

Parameters:

Parameter	Type	Description
$type	integer	Type

---

getThumbFileType

Get file type of original file.

PhotoSizeSourceThumbnail::getThumbFileType(  ): integer

---

getThumbFileTypeString

Get file type of original file as string.

PhotoSizeSourceThumbnail::getThumbFileTypeString(  ): string

---

setThumbFileType

Set file type of original file.

PhotoSizeSourceThumbnail::setThumbFileType( integer $_thumbFileType ): self

Parameters:

Parameter	Type	Description
$_thumbFileType	integer	File type of original file

---

getThumbType

Get thumbnail size.

PhotoSizeSourceThumbnail::getThumbType(  ): string

---

setThumbType

Set thumbnail size.

PhotoSizeSourceThumbnail::setThumbType( string $_thumbType ): self

Parameters:

Parameter	Type	Description
$_thumbType	string	Thumbnail size

---

UniqueFileId

Represents decoded unique bot API file ID.

• Full name: \danog\Decoder\UniqueFileId

__toString

Get unique bot API file ID.

UniqueFileId::__toString(  ): string

---

getUniqueBotAPI

Get unique bot API file ID.

UniqueFileId::getUniqueBotAPI(  ): string

---

fromUniqueBotAPI

Decode unique bot API file ID.

UniqueFileId::fromUniqueBotAPI( string $fileId ): self

• This method is static. Parameters:

Parameter	Type	Description
$fileId	string	Bot API file ID

---

fromBotAPI

Convert full bot API file ID to unique file ID.

UniqueFileId::fromBotAPI( string $fileId ): self

• This method is static. Parameters:

Parameter	Type	Description
$fileId	string	Full bot API file ID

---

fromFileId

Turn full file ID into unique file ID.

UniqueFileId::fromFileId( \danog\Decoder\FileId $fileId ): self

• This method is static. Parameters:

Parameter	Type	Description
$fileId	\danog\Decoder\FileId	Full file ID

---

getTypeName

Get unique file type as string.

UniqueFileId::getTypeName(  ): string

---

getType

Get unique file type.

UniqueFileId::getType(  ): integer

---

setType

Set file type.

UniqueFileId::setType( integer $_type ): self

Parameters:

Parameter	Type	Description
$_type	integer	File type.

---

getId

Get file ID.

UniqueFileId::getId(  ): integer

---

setId

Set file ID.

UniqueFileId::setId( integer $_id ): self

Parameters:

Parameter	Type	Description
$_id	integer	File ID.

---

hasId

Check if has ID.

UniqueFileId::hasId(  ): boolean

---

getVolumeId

Get photo volume ID.

UniqueFileId::getVolumeId(  ): integer

---

setVolumeId

Set photo volume ID.

UniqueFileId::setVolumeId( integer $_volumeId ): self

Parameters:

Parameter	Type	Description
$_volumeId	integer	Photo volume ID.

---

hasVolumeId

Check if has volume ID.

UniqueFileId::hasVolumeId(  ): boolean

---

getLocalId

Get photo local ID.

UniqueFileId::getLocalId(  ): integer

---

setLocalId

Set photo local ID.

UniqueFileId::setLocalId( integer $_localId ): self

Parameters:

Parameter	Type	Description
$_localId	integer	Photo local ID.

---

hasLocalId

Check if has local ID.

UniqueFileId::hasLocalId(  ): boolean

---

getUrl

Get weblocation URL.

UniqueFileId::getUrl(  ): string

---

setUrl

Set weblocation URL.

UniqueFileId::setUrl( string $_url ): self

Parameters:

Parameter	Type	Description
$_url	string	Weblocation URL

---

hasUrl

Check if has weblocation URL.

UniqueFileId::hasUrl(  ): boolean