php file downloader - Object Storage Service - Alibaba Cloud Documentation Center

This topic describes how to use the Downloader module in OSS SDK for PHP V2 to download files.

Notes

The sample code in this topic uses the public endpoint of the China (Hangzhou) region (cn-hangzhou). If you want to access OSS from other Alibaba Cloud services in the same region, you can use an internal endpoint. For more information about OSS region and endpoint mappings, see Regions and endpoints.
This topic provides an example of obtaining access credentials from environment variables. For more information, see Configure access credentials for PHP.
To download a file, you must have the oss:GetObject permission. For more information, see Grant custom permissions to a RAM user.

Method definition

Introduction to the Downloader feature

The Downloader module of OSS SDK for PHP V2 provides high-level interfaces that simplify the file download process by abstracting the underlying implementation details.

The Downloader module uses range download to automatically split a file into multiple smaller shards for concurrent download, which improves download performance.
The Downloader module also supports resumable download. During the download, the status of completed shards is recorded. If a download fails due to a network interruption or an unexpected program exit, you can use the breakpoint record file to resume the download from the last successful shard.

The following table describes the common methods of the Downloader module.

final class Downloader
{
	...
    public function __construct($client, array $args = [])
    
    public function downloadFile(Models\GetObjectRequest $request, string $filepath, array $args = []): Models\DownloadResult   
    
    public function downloadTo(Models\GetObjectRequest $request, \Psr\Http\Message\StreamInterface $stream, array $args = []): Models\DownloadResult
}

Request parameters

Parameter	Type	Description
request	GetObjectRequest	The request parameters for the object download. The parameters are the same as those of the GetObject operation.
filePath	string	The path of the local file.
args	array	(Optional) The configuration options.

The following table describes the common parameters in args.

Parameter	Type	Description
part_size	int	The shard size. The default value is 6 MiB.
parallel_num	int	The number of concurrent download tasks. The default value is 3. This parameter specifies the concurrency limit for a single call, not the global concurrency limit.
use_temp_file	bool	Specifies whether to use a temporary file when you download a file. By default, a temporary file is used. The file is first downloaded to a temporary file. After the download is successful, the temporary file is renamed to the object file.

When you instantiate a Downloader, you can specify configuration options to customize the download behavior. These options can be applied when you create the Downloader instance or for each individual download call.

Set the configuration parameters for the Downloader instance:

$d = $client->newDownloader(['part_size' => 10 * 1024 * 1024]);

Set the configuration parameters for each download request:

$d->downloadFile(
    new Oss\Models\GetObjectRequest(
        bucket: 'bucket',
        key: 'key'
    ),
    filepath: '/local/dir/example',
    args: ['part_size' => 10 * 1024 * 1024]
);

Sample code

You can use the following code to download a file from a bucket to your local machine.

<?php

// Import the autoload file to ensure that dependency libraries are correctly loaded.
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Define the description of command line arguments.
$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True], // The region where the bucket is located. (Required)
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False], // The endpoint. (Optional)
    "bucket" => ['help' => 'The name of the bucket', 'required' => True], // The name of the bucket. (Required)
    "key" => ['help' => 'The name of the object', 'required' => True], // The name of the object. (Required)
];

// Convert the argument descriptions to the long option format that is required by getopt.
// Add a colon (:) to the end of each argument to specify that a value is required.
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

// Parse the command line arguments.
$options = getopt("", $longopts);

// Verify that the required arguments exist.
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help']; // Obtain the help information about the argument.
        echo "Error: the following arguments are required: --$key, $help" . PHP_EOL;
        exit(1); // If a required argument is missing, exit the program.
    }
}

// Extract values from the parsed arguments.
$region = $options["region"]; // The region where the bucket is located.
$bucket = $options["bucket"]; // The name of the bucket.
$key = $options["key"];       // The name of the object.

// Load the credential information from environment variables.
// Use EnvironmentVariableCredentialsProvider to read the Access Key ID and Access Key Secret from environment variables.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// Use the default configurations of the SDK.
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider); // Set the credential provider.
$cfg->setRegion($region); // Set the region where the bucket is located.
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]); // If an endpoint is provided, set the endpoint.
}

// Create an OSS client instance.
$client = new Oss\Client($cfg);

// Create a downloader instance.
$downloader = $client->newDownloader();

// Define the local file path to save the downloaded content.
$filename = "/Users/yourLocalPath/yourFileName"; // An example of the file path.
touch($filename); // Create an empty file to ensure that the file exists.

// Perform the sharded download operation.
$result = $downloader->downloadFile(
    new Oss\Models\GetObjectRequest(
        bucket: $bucket,
        key: $key
    ),
    $filename
);

// Print the download result.
printf(
    'download status code:' . $result->statusCode . PHP_EOL .
    'download request id:' . $result->requestId . PHP_EOL .
    'download result:' . var_export($result, true) . PHP_EOL
);

Scenarios

Use Downloader to set the shard size and concurrency

You can use the following code to set the shard size and concurrency for the downloader.

<?php

// Import the autoload file to ensure that dependency libraries are correctly loaded.
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Define the description of command line arguments.
$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True], // The region where the bucket is located. (Required)
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False], // The endpoint. (Optional)
    "bucket" => ['help' => 'The name of the bucket', 'required' => True], // The name of the bucket. (Required)
    "key" => ['help' => 'The name of the object', 'required' => True], // The name of the object. (Required)
];

// Convert the argument descriptions to the long option format that is required by getopt.
// Add a colon (:) to the end of each argument to specify that a value is required.
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

// Parse the command line arguments.
$options = getopt("", $longopts);

// Verify that the required arguments exist.
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help']; // Obtain the help information about the argument.
        echo "Error: the following arguments are required: --$key, $help" . PHP_EOL;
        exit(1); // If a required argument is missing, exit the program.
    }
}

// Extract values from the parsed arguments.
$region = $options["region"]; // The region where the bucket is located.
$bucket = $options["bucket"]; // The name of the bucket.
$key = $options["key"];       // The name of the object.

// Load the credential information from environment variables.
// Use EnvironmentVariableCredentialsProvider to read the Access Key ID and Access Key Secret from environment variables.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// Use the default configurations of the SDK.
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider); // Set the credential provider.
$cfg->setRegion($region); // Set the region where the bucket is located.
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]); // If an endpoint is provided, set the endpoint.
}

// Create an OSS client instance.
$client = new Oss\Client($cfg);

// Create a downloader instance.
$downloader = $client->newDownloader();

// Define the parameters that are related to sharded download.
$partSize = 100 * 1024; // The shard size in bytes. In this example, the shard size is set to 100 KB.

// Define the local file path to save the downloaded content.
$filename = "/Users/yourLocalPath/yourFileName"; // An example of the file path.
touch($filename); // Create an empty file to ensure that the file exists.

// Perform the sharded download operation.
$result = $downloader->downloadFile(
    new Oss\Models\GetObjectRequest(
        bucket: $bucket,
        key: $key
    ),
    $filename,
    args: [ // Optional parameters that are used to customize the sharded download behavior.
        'part_size' => $partSize, // The custom shard size.
        'parallel_num' => 1,      // The number of shards that can be downloaded in parallel.
    ]
);

// Print the download result.
printf(
    'download status code:' . $result->statusCode . PHP_EOL .
    'download request id:' . $result->requestId . PHP_EOL .
    'download result:' . var_export($result, true) . PHP_EOL
);

Use Downloader to download to a stream

<?php

// Import the autoload file to ensure that dependency libraries are correctly loaded.
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Define the description of command line arguments.
$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True], // The region where the bucket is located. (Required)
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False], // The endpoint. (Optional)
    "bucket" => ['help' => 'The name of the bucket', 'required' => True], // The name of the bucket. (Required)
    "key" => ['help' => 'The name of the object', 'required' => True], // The name of the object. (Required)
];

// Convert the argument descriptions to the long option format that is required by getopt.
// Add a colon (:) to the end of each argument to specify that a value is required.
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

// Parse the command line arguments.
$options = getopt("", $longopts);

// Verify that the required arguments exist.
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help']; // Obtain the help information about the argument.
        echo "Error: the following arguments are required: --$key, $help" . PHP_EOL;
        exit(1); // If a required argument is missing, exit the program.
    }
}

// Extract values from the parsed arguments.
$region = $options["region"]; // The region where the bucket is located.
$bucket = $options["bucket"]; // The name of the bucket.
$key = $options["key"];       // The name of the object.

// Load the credential information from environment variables.
// Use EnvironmentVariableCredentialsProvider to read the Access Key ID and Access Key Secret from environment variables.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// Use the default configurations of the SDK.
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider); // Set the credential provider.
$cfg->setRegion($region); // Set the region where the bucket is located.
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]); // If an endpoint is provided, set the endpoint.
}

// Create an OSS client instance.
$client = new Oss\Client($cfg);

// Create a downloader instance.
$downloader = $client->newDownloader();

// Define a buffer stream to store the downloaded content.
$stream = new \GuzzleHttp\Psr7\BufferStream(1 * 1024 * 1024); // The buffer size is 1 MB.

// Perform the download operation to download the object content to the buffer stream.
$result = $downloader->downloadTo(
    request: new Oss\Models\GetObjectRequest(
        bucket: $bucket,
        key: $key // Specify the name of the object that you want to download.
    ),
    stream: $stream, // Specify the destination stream to store the downloaded content.
);

// Print the downloaded content.
printf(
    'download to body:' . $stream->getContents() . PHP_EOL // Output the content in the buffer stream.
);

References

For a complete downloader example, see GitHub example.