danog/MadelineProtoDocs
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Update file docs

Browse Source
This commit is contained in:
Daniil Gentili 2019-12-27 21:23:58 +01:00
parent 4bc0ee99f5
commit 1e235370a1
Signed by: danog
GPG Key ID: 8C1BE3B34B230CA7
3 changed files with 149 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

199
docs/docs/FILES.md
View File

@ -1,16 +1,17 @@
--- ---
title: Uploading and downloading files title: Uploading and downloading files
description: MadelineProto provides wrapper methods to upload and download files that support bot API file ids. description: MadelineProto provides **fully parallelized** wrapper methods to upload and download files that support bot API file ids, direct upload by URL and file renaming.
image: https://docs.madelineproto.xyz/favicons/android-chrome-256x256.png image: https://docs.madelineproto.xyz/favicons/android-chrome-256x256.png
--- ---
# Uploading and downloading files # Uploading and downloading files
MadelineProto provides wrapper methods to upload and download files that support bot API file ids. MadelineProto provides **fully parallelized** wrapper methods to upload and download files that support bot API file ids, direct upload by URL and file renaming.
Maximum file size is of 1.5 GB. Maximum file size is of 1.5 GB.
[Now fully async!](https://docs.madelineproto.xyz/docs/ASYNC.html) [Now fully async!](https://docs.madelineproto.xyz/docs/ASYNC.html)
* [Bot API file IDs](#bot-api-file-ids)
* [Uploading & sending files](#sending-files) * [Uploading & sending files](#sending-files)
* [Security notice](#security-notice) * [Security notice](#security-notice)
* [Photos](#inputmediauploadedphoto) * [Photos](#inputmediauploadedphoto)
@ -21,19 +22,23 @@ Maximum file size is of 1.5 GB.
* [Videos](#documentattributevideo-to-send-a-video) * [Videos](#documentattributevideo-to-send-a-video)
* [Audio & Voice](#documentattributeaudio-to-send-an-audio-file) * [Audio & Voice](#documentattributeaudio-to-send-an-audio-file)
* [Uploading files](#uploading-files) * [Uploading files](#uploading-files)
* [Bot API file IDs](#bot-api-file-ids)
* [Reusing uploaded files](#reusing-uploaded-files) * [Reusing uploaded files](#reusing-uploaded-files)
* [Renaming files](#renaming-files)
* [Downloading files](#downloading-files) * [Downloading files](#downloading-files)
* [Extracting download info](#extracting-download-info) * [Extracting download info](#extracting-download-info)
* [Downloading profile pictures](#downloading-profile-pictures) * [Downloading profile pictures](#downloading-profile-pictures)
* [Download to directory](#download-to-directory) * [Download to directory](#download-to-directory)
* [Download to file](#download-to-file) * [Download to file](#download-to-file)
* [Download to stream](#download-to-stream)
* [Download to callback](#download-to-callback)
* [Download to browser (streaming)](#download-to-browser-with-streams) * [Download to browser (streaming)](#download-to-browser-with-streams)
* [Getting progress](#getting-progress) * [Getting progress](#getting-progress)
## Sending files ## Sending files
To send photos and documents to someone, use the [$MadelineProto->messages->sendMedia](https://docs.madelineproto.xyz/API_docs/methods/messages_sendMedia.html) method, click on the link for more info. To send photos and documents to someone, use the [$MadelineProto->messages->sendMedia](https://docs.madelineproto.xyz/API_docs/methods/messages.sendMedia.html) method, click on the link for more info.
All files will be uploaded **asynchronously and in parallel**, 3000 chunks at a time for maximum performance (this value can be tweaked in the [settings](https://docs.madelineproto.xyz/docs/SETTINGS.html)).
The required `message` parameter is the caption: it can contain URLs, mentions, bold and italic text, thanks to the `parse_mode` parameter, that enables markdown or HTML parsing. The required `message` parameter is the caption: it can contain URLs, mentions, bold and italic text, thanks to the `parse_mode` parameter, that enables markdown or HTML parsing.
@ -60,7 +65,8 @@ $sentMessage = yield $MadelineProto->messages->sendMedia([
]); ]);
``` ```
Can be used to upload photos: simply provide the photo's file path in the `file` field, and optionally provide a `ttl_seconds` field to set the self-destruction period of the photo, even for normal chats Can be used to upload photos: simply provide the photo's file path in the `file` field, and optionally provide a `ttl_seconds` field to set the self-destruction period of the photo, even for normal chats.
You can also provide a URL to the `file` field.
### [inputMediaUploadedDocument](https://docs.madelineproto.xyz/API_docs/constructors/inputMediaUploadedDocument.html) ### [inputMediaUploadedDocument](https://docs.madelineproto.xyz/API_docs/constructors/inputMediaUploadedDocument.html)
```php ```php
@ -79,6 +85,8 @@ $sentMessage = yield $MadelineProto->messages->sendMedia([
``` ```
Can be used to upload documents, videos, gifs, voice messages, round videos, round voice messages: simply provide the file's file path in the `file` field, and optionally provide a `ttl_seconds` field to set the self-destruction period of the photo, even for normal chats. Can be used to upload documents, videos, gifs, voice messages, round videos, round voice messages: simply provide the file's file path in the `file` field, and optionally provide a `ttl_seconds` field to set the self-destruction period of the photo, even for normal chats.
You can also provide a URL to the `file` field.
To rename files, provide an Update or another already-uploaded Telegram file object to the `file` field.
You must also provide the file's mime type in the `mime_type` field, generate it using `mime_content_type($file_path);` (tip: try using an unexpected mime type to make official clients crash ;). You must also provide the file's mime type in the `mime_type` field, generate it using `mime_content_type($file_path);` (tip: try using an unexpected mime type to make official clients crash ;).
Use the `nosound_video` field if the video does not have sound (gifs). Use the `nosound_video` field if the video does not have sound (gifs).
To actually set the document type, provide one or more [DocumentAttribute](https://docs.madelineproto.xyz/API_docs/types/DocumentAttribute.html) objects to the `attributes` field: To actually set the document type, provide one or more [DocumentAttribute](https://docs.madelineproto.xyz/API_docs/types/DocumentAttribute.html) objects to the `attributes` field:
@ -185,9 +193,13 @@ $MessageMedia = yield $MadelineProto->messages->uploadMedia([
]); ]);
``` ```
The `file` can be a file name, a URL, or a file uploaded by someone else (can be used to rename files).
You can also only upload a file, without actually sending it to anyone, storing only the file ID for later usage. You can also only upload a file, without actually sending it to anyone, storing only the file ID for later usage.
The [$MadelineProto->messages->uploadMedia](https://docs.madelineproto.xyz/API_docs/methods/messages_uploadMedia.html) function is a reduced version of the [$MadelineProto->messages->sendMedia](https://docs.madelineproto.xyz/API_docs/methods/messages_sendMedia.html), that requires only a `media` parameter, with the media to upload. All files will be uploaded **asynchronously and in parallel**, 3000 chunks at a time for maximum performance (this value can be tweaked in the [settings](https://docs.madelineproto.xyz/docs/SETTINGS.html)).
The [$MadelineProto->messages->uploadMedia](https://docs.madelineproto.xyz/API_docs/methods/messages_uploadMedia.html) function is a reduced version of the [$MadelineProto->messages->sendMedia](https://docs.madelineproto.xyz/API_docs/methods/messages_sendMedia.html), that requires only a `media` parameter, with the media to upload (on normal users, the `peer` field should be populated with `@me` or another value).
The returned [MessageMedia](https://docs.madelineproto.xyz/API_docs/types/MessageMedia.html) object can then be reused to resend the document using sendMedia. The returned [MessageMedia](https://docs.madelineproto.xyz/API_docs/types/MessageMedia.html) object can then be reused to resend the document using sendMedia.
@ -202,65 +214,43 @@ $sentMessage = yield $MadelineProto->messages->sendMedia([
`$MessageMedia` can also be a [Message](https://docs.madelineproto.xyz/API_docs/types/Message.html) (the media contained in the message will be sent), an [Update](https://docs.madelineproto.xyz/API_docs/types/Update.html) (the media contained in the message contained in the update will be sent). `$MessageMedia` can also be a [Message](https://docs.madelineproto.xyz/API_docs/types/Message.html) (the media contained in the message will be sent), an [Update](https://docs.madelineproto.xyz/API_docs/types/Update.html) (the media contained in the message contained in the update will be sent).
## Bot API file IDs
`$MessageMedia` can even be a bot API file ID, generated by the bot API, or by MadelineProto:
Actual MessageMedia objects can also be converted to bot API file IDs like this:
```php
$botAPI_file = yield $MadelineProto->MTProto_to_botAPI($MessageMedia);
```
`$botAPI_file` now contains a [bot API message](https://core.telegram.org/bots/api#message), to extract the file ID from it use the following code:
```php
foreach (['audio', 'document', 'photo', 'sticker', 'video', 'voice', 'video_note'] as $type) {
if (isset($botAPI_file[$type]) && is_array($botAPI_file[$type])) {
$method = $type;
}
}
$result['file_type'] = $method;
if ($result['file_type'] == 'photo') {
$result['file_size'] = $botAPI_file[$method][0]['file_size'];
if (isset($botAPI_file[$method][0]['file_name'])) {
$result['file_name'] = $botAPI_file[$method][0]['file_name'];
$result['file_id'] = $botAPI_file[$method][0]['file_id'];
}
} else {
if (isset($botAPI_file[$method]['file_name'])) {
$result['file_name'] = $botAPI_file[$method]['file_name'];
}
if (isset($botAPI_file[$method]['file_size'])) {
$result['file_size'] = $botAPI_file[$method]['file_size'];
}
if (isset($botAPI_file[$method]['mime_type'])) {
$result['mime_type'] = $botAPI_file[$method]['mime_type'];
}
$result['file_id'] = $botAPI_file[$method]['file_id'];
}
if (!isset($result['mime_type'])) {
$result['mime_type'] = 'application/octet-stream';
}
if (!isset($result['file_name'])) {
$result['file_name'] = $result['file_id'].($method === 'sticker' ? '.webp' : '');
}
```
* `$result['file_id']` - Bot API file ID
* `$result['mime_type']` - Mime type
* `$result['file_type']` - File type: voice, video, video_note (round video), music, video, photo, sticker or document
* `$result['file_size']` - File size
* `$result['file_name']` - File name
## Reusing uploaded files ## Reusing uploaded files
`$MadelineProto->messages->uploadMedia` and bot API file IDs do not allow you to modify the type of the file to send: however, MadelineProto provides a method that can generate a file object that can be resent with multiple file types. `$MadelineProto->messages->uploadMedia` and bot API file IDs do not allow you to modify the type of the file to send: however, MadelineProto provides methods that can generate a file object that can be resent with multiple file types.
```php ```php
$inputFile = yield $MadelineProto->upload('filename.mp4'); $inputFile = yield $MadelineProto->upload('filename.mp4');
``` ```
The file name can also be a URL.
More optional parameters are available, check the PHPDOC of the method in your IDE.
You can also upload a file from a stream (this is especially useful, for example, when downloading YouTube videos using `youtube-dl` with `ffmpeg` and [async AMPHP CLI streams](https://github.com/amphp/process)):
```php
$inputFile = yield $MadelineProto->uploadFromStream($stream, $size, $mime);
```
`$stream` - PHP resource or [async AMPHP stream](https://github.com/amphp/byte-stream).
`$size` - Size of file to upload
`$mime` - MIME type of file to upload
More optional parameters are available, check the PHPDOC of the method in your IDE.
You can also upload files from a callable:
```php
$inputFile = yield $MadelineProto->uploadFromCallable($callable, $size, $mime);
```
`$callable`:
The callable must accept two parameters: `int $offset, int $size`
The callable must return a string with the contest of the file at the specified offset and size.
`$size` - Size of file to upload
`$mime` - MIME type of file to upload
More optional parameters are available, check the PHPDOC of the method in your IDE.
---
The generated `$inputFile` can later be reused thusly: The generated `$inputFile` can later be reused thusly:
```php ```php
@ -294,6 +284,24 @@ In this case, we're reusing the same InputFile to send both a document and a vid
The concept is easy: where you would usually provide a file path, simply provide `$inputFile`. The concept is easy: where you would usually provide a file path, simply provide `$inputFile`.
## Renaming files
Files can be renamed by simply providing the `$Update` with the file to the sendMedia method thusly:
```php
$sentMessage = yield $MadelineProto->messages->sendMedia([
'peer' => '@danogentili',
'media' => [
'_' => 'inputMediaUploadedDocument',
'file' => $Update,
'attributes' => [
['_' => 'documentAttributeFilename', 'file_name' => $newName]
]
],
'message' => '[This is the caption](https://t.me/MadelineProto)',
'parse_mode' => 'Markdown'
]);
```
## Downloading files ## Downloading files
@ -317,7 +325,7 @@ $info = yield $MadelineProto->getPropicInfo($Update);
``` ```
`$Update` can be a [Message](https://docs.madelineproto.xyz/API_docs/types/Message.html) object, an [Update](https://docs.madelineproto.xyz/API_docs/types/Update.html), or any value supported by [getInfo](https://docs.madelineproto.xyz/getInfo.html). `$Update` can be a [Message](https://docs.madelineproto.xyz/API_docs/types/Message.html) object, an [Update](https://docs.madelineproto.xyz/API_docs/types/Update.html), or any value supported by [getInfo](https://docs.madelineproto.xyz/getInfo.html).
The result (which is in the same format as `get_download_info`) should the be passed to the download functions in order to download the profile picture. The result (which is in the same format as `getDownloadInfo`) should the be passed to the download functions in order to download the profile picture.
* `$info['ext']` - The file extension * `$info['ext']` - The file extension
* `$info['name']` - The file name, without the extension * `$info['name']` - The file name, without the extension
@ -342,6 +350,27 @@ This downloads the given file to `/tmp/myname.mp4`, and returns the full file pa
`$MessageMedia`can be either a [Message](https://docs.madelineproto.xyz/API_docs/types/Message.html), an [Update](https://docs.madelineproto.xyz/API_docs/types/Update.html), a [MessageMedia](https://docs.madelineproto.xyz/API_docs/types/MessageMedia.html) object, or a bot API file ID. `$MessageMedia`can be either a [Message](https://docs.madelineproto.xyz/API_docs/types/Message.html), an [Update](https://docs.madelineproto.xyz/API_docs/types/Update.html), a [MessageMedia](https://docs.madelineproto.xyz/API_docs/types/MessageMedia.html) object, or a bot API file ID.
### Download to stream
```php
yield $MadelineProto->downloadToStream($MessageMedia, $stream);
```
This downloads the given file to the given resource or [async AMPHP stream](https://github.com/amphp/byte-stream).
`$MessageMedia`can be either a [Message](https://docs.madelineproto.xyz/API_docs/types/Message.html), an [Update](https://docs.madelineproto.xyz/API_docs/types/Update.html), a [MessageMedia](https://docs.madelineproto.xyz/API_docs/types/MessageMedia.html) object, or a bot API file ID.
### Download to callback
```php
yield $MadelineProto->downloadToCallable($MessageMedia, $callable);
```
This downloads the given file to the callable.
The callable must accept two parameters: `string $payload, int $offset`
The callable will be called (possibly out of order, depending on the value of the `$seekable` (see PHPDOC)).
The callable should return the number of written bytes.
`$MessageMedia`can be either a [Message](https://docs.madelineproto.xyz/API_docs/types/Message.html), an [Update](https://docs.madelineproto.xyz/API_docs/types/Update.html), a [MessageMedia](https://docs.madelineproto.xyz/API_docs/types/MessageMedia.html) object, or a bot API file ID.
### Download to browser with streams ### Download to browser with streams
```php ```php
@ -447,4 +476,56 @@ $output_file_name = yield $MadelineProto->downloadToFile(
); );
``` ```
## Bot API file IDs
`$MessageMedia` can even be a bot API file ID, generated by the bot API, or by MadelineProto:
Actual MessageMedia objects can also be converted to bot API file IDs like this:
```php
$botAPI_file = yield $MadelineProto->MTProto_to_botAPI($MessageMedia);
```
`$botAPI_file` now contains a [bot API message](https://core.telegram.org/bots/api#message), to extract the file ID from it use the following code:
```php
foreach (['audio', 'document', 'photo', 'sticker', 'video', 'voice', 'video_note'] as $type) {
if (isset($botAPI_file[$type]) && is_array($botAPI_file[$type])) {
$method = $type;
}
}
$result['file_type'] = $method;
if ($result['file_type'] == 'photo') {
$result['file_size'] = $botAPI_file[$method][0]['file_size'];
if (isset($botAPI_file[$method][0]['file_name'])) {
$result['file_name'] = $botAPI_file[$method][0]['file_name'];
$result['file_id'] = $botAPI_file[$method][0]['file_id'];
}
} else {
if (isset($botAPI_file[$method]['file_name'])) {
$result['file_name'] = $botAPI_file[$method]['file_name'];
}
if (isset($botAPI_file[$method]['file_size'])) {
$result['file_size'] = $botAPI_file[$method]['file_size'];
}
if (isset($botAPI_file[$method]['mime_type'])) {
$result['mime_type'] = $botAPI_file[$method]['mime_type'];
}
$result['file_id'] = $botAPI_file[$method]['file_id'];
}
if (!isset($result['mime_type'])) {
$result['mime_type'] = 'application/octet-stream';
}
if (!isset($result['file_name'])) {
$result['file_name'] = $result['file_id'].($method === 'sticker' ? '.webp' : '');
}
```
* `$result['file_id']` - Bot API file ID
* `$result['mime_type']` - Mime type
* `$result['file_type']` - File type: voice, video, video_note (round video), music, video, photo, sticker or document
* `$result['file_size']` - File size
* `$result['file_name']` - File name
<a href="https://docs.madelineproto.xyz/docs/CHAT_INFO.html">Next section</a> <a href="https://docs.madelineproto.xyz/docs/CHAT_INFO.html">Next section</a>

2
docs/docs/INSTALLATION.md
View File

@ -91,4 +91,4 @@ Then you can require the package:
composer require danog/madelineproto composer require danog/madelineproto
``` ```
<a href="https://docs.madelineproto.xyz/docs/UPDATES.html">Next section</a> <a href="https://docs.madelineproto.xyz/docs/UPDATES.html">Next section</a>

8
docs/docs/SETTINGS.md
View File

@ -318,6 +318,10 @@ Description: Can be true to accept all secret chats, false to not accept any sec
Upload settings Upload settings
### `$settings['upload']['parallel_chunks']`
Default: `20`
Description: Default number of chunks for parallel upload
### `$settings['upload']['allow_automatic_upload']` ### `$settings['upload']['allow_automatic_upload']`
Default: `true` Default: `true`
Description: If false, [disables automatic upload from file path in constructors](FILES.html) Description: If false, [disables automatic upload from file path in constructors](FILES.html)
@ -331,6 +335,10 @@ Description: Default part size for file upload
Download settings Download settings
### `$settings['download']['parallel_chunks']`
Default: `20`
Description: Default number of chunks for parallel download
### `$settings['download']['part_size']` ### `$settings['download']['part_size']`
Default: `1024*1024` Default: `1024*1024`
Description: Default part size for file download Description: Default part size for file download