From 4a455d250591edbdcd3744a194daf67536484358 Mon Sep 17 00:00:00 2001 From: Daniil Gentili Date: Mon, 1 Apr 2024 18:03:39 +0200 Subject: [PATCH] Bump docs --- .gitignore | 1 + README.md | 67 ++++++++++++++++----------------------- src/FileIdType.php | 36 ++++++++++++++++++++- src/Tools.php | 1 + src/UniqueFileIdType.php | 5 +++ tests/IntegrationTest.php | 2 +- 6 files changed, 70 insertions(+), 42 deletions(-) diff --git a/.gitignore b/.gitignore index 1088a3b..2838b93 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ +coverage .phpunit.cache MadelineProtoPhar JSON.sh diff --git a/README.md b/README.md index cbdea4c..af5fdb5 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ![build](https://github.com/danog/tg-file-decoder/workflows/build/badge.svg) -Decode [Telegram bot API file IDs](https://core.telegram.org). +Decode and encode [Telegram bot API file IDs](https://core.telegram.org)! ## Install @@ -10,8 +10,6 @@ Decode [Telegram bot API file IDs](https://core.telegram.org). composer require danog/tg-file-decoder ``` -On 32-bit systems, [phpseclib](https://github.com/phpseclib/phpseclib) is also required. - ## Examples: ### Decoding bot API file IDs @@ -22,32 +20,30 @@ 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 +$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->getDcId(); // On which datacenter is this file stored +$dcId = $fileId->dcId; // On which datacenter is this file stored -$type = $fileId->getType(); // File type -$typeName = $fileId->getTypeName(); // File type (as string) +$type = $fileId->type; // File type -$id = $fileId->getId(); -$accessHash = $fileId->getAccessHash(); +$id = $fileId->id; +$accessHash = $fileId->accessHash; -$fileReference = $fileId->getFileReference(); // File reference, https://core.telegram.org/api/file_reference -$url = $fileId->getUrl(); // URL, file IDs with encoded webLocation +$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() <= PHOTO) -$volumeId = $fileId->getVolumeID(); -$localId = $fileId->getLocalID(); +// For photos, thumbnails if ($fileId->getType() <= FileIdType::PHOTO->value) +$volumeId = $fileId->volumeId; +$localId = $fileId->localId; -// if $fileId->hasPhotoSizeSource() -$photoSizeSource = $fileId->getPhotoSizeSource(); // PhotoSizeSource object -$photoSizeSource->getDialogId(); -$photoSizeSource->getStickerSetId(); +$photoSizeSource = $fileId->photoSizeSource; // PhotoSizeSource object +$photoSizeSource->dialogId; +$photoSizeSource->stickerSetId; // And more, depending on photosize source ``` @@ -62,17 +58,14 @@ For photosize source, see [here](#photosize-source). ```php $uniqueFileId = UniqueFileId::fromUniqueBotAPI('AgADrQEAArE4rFE'); -$type = $fileId->getType(); // Unique file type -$typeName = $fileId->getTypeName(); // Unique file type (as string) +$type = $fileId->type; // Unique file type -$id = $uniqueFileId->getId(); -$accessHash = $uniqueFileId->getAccessHash(); -$url = $uniqueFileId->getUrl(); // URL, for unique file IDs with encoded webLocation -// You can also use hasUrl +$id = $uniqueFileId->id; +$url = $uniqueFileId->url; // URL, for unique file IDs with encoded webLocation // For photos -$volumeId = $uniqueFileId->getVolumeID(); -$localId = $uniqueFileId->getLocalID(); +$volumeId = $uniqueFileId->volumeId; +$localId = $uniqueFileId->localId; ``` For unique file types, see [unique types](#bot-api-unique-file-id-types). @@ -98,25 +91,19 @@ var_dump(((string) $uniqueFileId) === ((string) $uniqueFileIdExtracted2)); // tr ```php $fileId = FileId::fromString('CAACAgQAAxkDAAJEsl44nl3yxPZ8biI8uhaA7rbQceOSAAKtAQACsTisUXvMEbVnTuQkGAQ'); -$photoSizeSource = $fileId->getPhotoSizeSource(); // PhotoSizeSource object +$photoSizeSource = $fileId->photoSizeSource; // PhotoSizeSource object -$sourceType = $photoSizeSource->getType(); +$sourceType = $photoSizeSource->type; // If $sourceType === PHOTOSIZE_SOURCE_DIALOGPHOTO_SMALL|PHOTOSIZE_SOURCE_DIALOGPHOTO_SMALL or // If $photoSizeSource instanceof PhotoSizeSourceDialogPhoto -$dialogId = $photoSizeSource->getDialogId(); -$dialogId = $photoSizeSource->getStickerSetId(); +$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. -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](#photosizesourcelegacy) class. -* `const PHOTOSIZE_SOURCE_THUMBNAIL = 1` - Used for document and photo thumbnail, returns [PhotoSizeSourceThumbnail](#photosizesourcethumbnail) class. -* `const PHOTOSIZE_SOURCE_DIALOGPHOTO_SMALL = 2` - Used for dialog photos, returns [PhotoSizeSourceDialogPhoto](#photosizesourcedialogphoto) class. -* `const PHOTOSIZE_SOURCE_DIALOGPHOTO_BIG = 3` - Used for dialog photos, returns [PhotoSizeSourceDialogPhoto](#photosizesourcedialogphoto) class. -* `const PHOTOSIZE_SOURCE_STICKERSET_THUMBNAIL = 4` - Used for document and photo thumbnails, returns [PhotoSizeSourceThumbnail](#photosizesourcethumbnail) class. +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 @@ -132,8 +119,6 @@ $fileId->setAccessHash($customHash); $encoded = (string) $fileId; // CAACAgQAAxkDAAJEsl44nl3yxPZ8biI8uhaA7rbQceOSAAKtAQACsTisUXvMEbVnTuQkGAQ, or something ``` -All classes, from [FileId](#fileid), to [UniqueFileID](#uniquefileid), to [PhotoSizeSource](PhotoSizeSourceDialogPhoto) 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). @@ -182,3 +167,5 @@ The `FULL_UNIQUE_MAP` array contains a `full file type` => `unique file type` ma * `const UNIQUE_TEMP = 5` - Used for temp files ## Full API documentation + +Click [here »](https://github.com/danog/tg-file-decoder/blob/master/docs/index.md) to view the full API documentation. \ No newline at end of file diff --git a/src/FileIdType.php b/src/FileIdType.php index a15fa7b..798791b 100644 --- a/src/FileIdType.php +++ b/src/FileIdType.php @@ -20,6 +20,11 @@ namespace danog\Decoder; use AssertionError; +/** + * Represents decoded bot API file ID type. + * + * @api + */ enum FileIdType: int { /** @@ -96,8 +101,10 @@ enum FileIdType: int * Size. */ case SIZE = 17; - case NONE = 18; + /** + * Obtain a FileId enum variant from a bot API type name. + */ public static function fromBotApiType(string $type): self { return match ($type) { @@ -122,6 +129,33 @@ enum FileIdType: int }; } + /** + * Obtain a bot API type name. + */ + public function toBotApiType(): string + { + return match ($this) { + self::THUMBNAIL => 'thumbnail' , + self::PROFILE_PHOTO => 'profile_photo', + self::PHOTO =>'photo' , + self::VOICE=>'voice' , + self::VIDEO =>'video' , + self::DOCUMENT=> 'document' , + self::ENCRYPTED =>'encrypted' , + self::TEMP =>'temp', + self::STICKER =>'sticker', + self::AUDIO =>'audio', + self::ANIMATION =>'animation', + self::ENCRYPTED_THUMBNAIL =>'encrypted_thumbnail', + self::WALLPAPER =>'wallpaper', + self::VIDEO_NOTE =>'video_note', + self::SECURE_RAW =>'secure_raw', + self::SECURE =>'secure', + self::BACKGROUND=>'background', + self::SIZE=>'size', + }; + } + /** * Convert file ID type to unique file ID type. */ diff --git a/src/Tools.php b/src/Tools.php index fdc555e..eb59738 100644 --- a/src/Tools.php +++ b/src/Tools.php @@ -4,6 +4,7 @@ namespace danog\Decoder; \define('BIG_ENDIAN', \pack('L', 1) === \pack('N', 1)); +/** @internal */ final class Tools { public const WEB_LOCATION_FLAG = 1 << 24; diff --git a/src/UniqueFileIdType.php b/src/UniqueFileIdType.php index 09f199d..e3962c4 100644 --- a/src/UniqueFileIdType.php +++ b/src/UniqueFileIdType.php @@ -18,6 +18,11 @@ namespace danog\Decoder; +/** + * Represents decoded unique bot API file ID type. + * + * @api + */ enum UniqueFileIdType: int { case WEB = 0; diff --git a/tests/IntegrationTest.php b/tests/IntegrationTest.php index 98bced3..72ac13f 100644 --- a/tests/IntegrationTest.php +++ b/tests/IntegrationTest.php @@ -9,7 +9,7 @@ use danog\Decoder\UniqueFileId; use PHPUnit\Framework\Attributes\DataProvider; use PHPUnit\Framework\TestCase; -/** @api */ +/** @internal */ class IntegrationTest extends TestCase { #[DataProvider('provideFileIdsAndType')]