目录操作

S3 传输管理器可以处理整个目录传输。

上传目录

S3 传输管理器可以将整个目录上传到 S3 存储桶。 <Are the key values the filenames when uploaded?>

<?php

use Aws\S3\S3Transfer\Models\UploadDirectoryRequest;
use Aws\S3\S3Transfer\S3TransferManager;

require __DIR__ . '/../vendor/autoload.php';


$transferManager = new S3TransferManager(null, [
    'default_region' => 'us-west-2'
]);

$uploadDirPromise = $transferManager->uploadDirectory(
    new UploadDirectoryRequest(
        '/path/to/local/directory',
        'amzn-s3-demo-bucket',
        [
            // Additional `putObject` parameters that apply to all files.
            'ACL'          => 'public-read',
            'CacheControl' => 'max-age=3600',
        ],
        [
            // Configuration options.
            'recursive'                      => true,
            'follow_symbolic_links'          => false,
            's3_prefix'                      => 'uploads/2023/',
            's3_delimiter'                   => '/',
            'track_progress'                 => true,
            'filter'                         => function ($file) {
                // Upload only .jpg files.
                return pathinfo($file, PATHINFO_EXTENSION) === 'jpg';
            },
            'upload_object_request_modifier' => function ($args) {
                // Customize request arguments for each file.
                $args['ContentType'] = 'image/jpeg';
            },
        ]
    )
);

// Wait for the upload process to complete.
$result = $uploadDirPromise->wait();

$uploaded = $result->getObjectsUploaded();
$failed = $result->getObjectsFailed();
echo "Uploaded {$uploaded} files. Failed: {$failed}\n";

uploadDirectory 方法参数

该uploadDirectory方法接受的实例UploadDirectoryRequest<add link>作为参数。

UploadDirectoryRequest 参数

当该uploadDirectory方法成功运行时，它将返回UploadDirectoryResult<add link>。

下载目录

您可以从 S3 存储桶下载目录。 <Are the filenames the key values when downloaded? If there is no extension in the key, is there also no extension on the file?>

<?php

use Aws\S3\S3Transfer\Models\DownloadDirectoryRequest;
use Aws\S3\S3Transfer\S3TransferManager;

require __DIR__ . '/../vendor/autoload.php';


$transferManager = new S3TransferManager(null, [
    'default_region' => 'us-west-2'
]);

$downloadDirPromise = $transferManager->downloadDirectory(
    new DownloadDirectoryRequest(
        'amzn-s3-demo-bucket',
        '/path/to/local/directory',
        [
            // Additional `getObject` parameters that apply to all files.
        ],
        [
            // Configuration options.
            's3_prefix'                        => 'uploads/2023/',
            's3_delimiter'                     => '/',
            'track_progress'                   => true,
            'filter'                           => function ($key) {
                // Download only .jpg files.
                return pathinfo($key, PATHINFO_EXTENSION) === 'jpg';
            },
            'download_object_request_modifier' => function ($args) {
                // Customize request arguments for each file.
                $args['ResponseContentType'] = 'image/jpeg';
            },
            'list_objects_v2_args'              => [
                'MaxKeys' => 1000,
                'Prefix'  => 'uploads/2023/',
            ],
            'fails_when_destination_exists'    => true,
        ]
    )
);

// Wait for the download process to complete.
$result = $downloadDirPromise->wait();

$downloaded = $result->getObjectsDownloaded();
$failed = $result->getObjectsFailed();
echo "Downloaded {$downloaded} files. Failed: {$failed}\n";

downloadDirectory 方法参数

该downloadDirectory方法接受的实例DownloadDirectoryRequest<add link>作为参数。

DownloadDirectoryRequest 参数

目录操作的工作原理

本节介绍 S3 传输管理器在目录操作期间如何处理文件路径和对象密钥。

上传路径处理

上传目录时，SDK 会根据文件路径构造 S3 对象密钥：

该recursive选项控制是否包含子目录。false（默认）时，仅上传顶级文件。当true上传子目录中的所有文件时，在对象密钥中保留目录结构。

$sourceDirectory = "/opt/my-upload-directory";
$s3Prefix = "important/";
$s3Delimiter = "/"; // Default value

/opt/my-upload-directory/
-- my-file1.txt
-- my-file-2.txt
-- sub-dir/
---- my-another-file1.txt
---- my-another-file2.txt

$s3Prefix + $fileRelativePath;

- important/my-file1.txt
- important/my-file-2.txt
- important/sub-dir/my-another-file1.txt
- important/sub-dir/my-another-file2.txt

$sourceDirectory = "/opt/my-docs";
$s3Prefix = ''; // No provided and it will defaulted to empty string
$s3Delimiter = "/"; // Default value

/opt/my-docs/
-- my-file1.txt
-- my-file-2.txt
-- sub-dir/
---- my-another-file1.txt
---- my-another-file2.txt

$s3Prefix + $fileRelativePath;

- my-file1.txt
- my-file-2.txt
- sub-dir/my-another-file1.txt
- sub-dir/my-another-file2.txt

<?php
// Source directory: /home/user/photos/
//   fla/beach.jpg
//   fla/sunset.jpg
//   fla/pool/party.jpg
// With s3_prefix: '2023' and recursive: true
// Results:
//   2023/fla/beach.jpg
//   2023/fla/sunset.jpg
//   2023/fla/pool/party.jpg

下载路径处理

下载目录时，SDK 会根据 S3 对象密钥构造本地文件路径：

下载总是递归的。SDK 会检索指定前缀下的所有对象，并根据需要创建子目录。为了安全起见，它会验证路径不会解析到目标目录之外的路径。

<?php
// S3 objects:
//   2023/fla/beach.jpg
//   2023/fla/sunset.jpg
//   2023/fla/pool/party.jpg
// With s3_prefix: '2023' and destination: /home/user/downloads
// Results:
//   /home/user/downloads/fla/beach.jpg
//   /home/user/downloads/fla/sunset.jpg
//   /home/user/downloads/fla/pool/party.jpg

$s3Prefix = "my-prefix";
$s3Objects = [
    "my-prefix/file-1.txt", 
    "my-prefix/file-2.txt", 
    "my-prefix/subdir/file-1.txt"
];
$targetDirectory = "/opt/bucket/downloads/";

/opt/bucket/downloads/
-- file-1.txt
-- file-2.txt
-- subdir/
---- file-1.txt

$s3Prefix = ""; // No provided
$s3Objects = [
    "README.md",
    "my-docs/file-1.txt", 
    "my-docs/file-2.txt", 
    "my-docs/statements/file-1.txt"
];
$targetDirectory = "/opt/bucket/downloads/";

/opt/bucket/downloads/
-- README.md
-- my-docs/
---- file-1.txt
---- file-2.txt
---- statements/
------ file-1.txt