README

概述

此Laravel扩展包包含了目前Laravel中尚未提供的与亚马逊S3服务交互的功能。特别是，它提供了处理S3中版本化对象的方法。它简单地扩展了现有的核心类来支持S3中的版本控制，并连接到Storage外观以方便使用。它被设计为可替换的，与核心功能向后兼容，因此不应该存在任何冲突。我最初开发此包是为了满足自己处理S3中版本化对象的需求，并希望利用Laravel的Storage外观的便利性。

使用此包，您可以轻松地

• 管理存储在S3中的版本化对象
  • 获取存储在S3中的特定对象的版本列表
  • 检索存储在S3中的特定对象的特定版本
  • 删除存储在S3中的特定对象的特定版本
• 设置或清除亚马逊S3/API选项值
• 对您的对象执行其他亚马逊S3/API命令

未来可能会添加其他方法和便利性，这主要取决于我的需求或社区的建议。欢迎提交拉取请求、错误报告等！：）

注意：是的，我知道您可以利用底层亚马逊S3 API包来做这些事情。但我想利用它们与Storage外观的便利性，以及未来可能的一些附加功能。所以，如果您愿意这样做

// Instantiate an Amazon S3 client.
$s3 = new S3Client([
	'version' => 'latest',
	'region'  => 'us-west-2'
]);

// Fetch the latest version of a file
try {
    $s3->putObject([
        'Bucket' => 'my-bucket',
        'Key'    => 'myfile.png',
				'VersionId' => 'fiWFsPPFwbvlGh37rB9IaZYkO4pzOgWGz'
    ]);
} catch (Aws\S3\Exception\S3Exception $e) {
    echo "There was an error retrieving the file.\n";
}

... 而不是这样做

$file = Storage::disk('s3-tools')->getVersion($versionId)->get('myfile.png');

... 那就是您的事了。祝您玩得开心。：）

要求

此包假定您已经安装了以下包

• league/flysystem
• league/flysystem-aws-s3-v3
• aws/aws-sdk-php

Laravel已经安装了league/flysystem包，但您可能需要安装其他包。我已经将它们作为依赖项添加到此包中，所以无论如何，它应该对您来说都是自动的。

安装

您可以通过Composer安装此包

composer require incursus/laravel-s3-tools

安装后，您需要像往常一样将服务提供者添加到您的config/app.php文件中（对于不支持自动发现的Laravel 5.5之前的版本）

	...
	'providers' => [
		...
		Incursus\LaravelS3Tools\S3ToolsServiceProvider::class,
		...
	],
	...

配置

环境变量

AWS环境变量

laravel-s3-tools包利用了Laravel中现有的AWS/S3配置，因此如果您已经配置了您的应用程序以使用S3，那么您就可以开始了！当然，前提是您正在使用最新的AWS/S3配置语句（这些配置语句在Laravel中不久前进行了更改）。为了确保这一点，请检查您的.env文件中的以下内容

AWS_ACCESS_KEY_ID=<YOUR KEY>
AWS_SECRET_ACCESS_KEY=<YOUR SECRET>
AWS_DEFAULT_REGION=<DEFAULT REGION>
AWS_BUCKET=<YOUR BUCKET NAME>

如果您不确定在AWS_DEFAULT_REGION中使用什么值，请查看此页面获取更多信息（使用该页面上表的“区域”列中显示的值。）

S3工具磁盘名称

默认情况下，此包将使用磁盘名称s3-tools。如果您想将其重命名为其他名称，您可以在.env文件中使用S3_TOOLS_DISK_NAME环境变量，如下所示。

S3_TOOLS_DISK_NAME="diskname"

磁盘配置

《laravel-s3-tools》包需要您在您的 config/filesystems.php 文件中设置一个新的磁盘配置。实际上非常简单。只需复制下面的条目并将其粘贴到您的 config/filesystems.php 文件中。它将自动在您的 .env 文件中查找自定义磁盘名称，如果未找到，将回退到默认值 s3-tools。此磁盘名称将是您在 Storage 面具中使用的磁盘，每次您想要利用此包的功能时。新的磁盘配置也可以用于普通的、非版本的 S3 操作，或者您也可以只使用原始的 's3' 配置。由您决定！

因此，您的 config/filesystems.php 文件应该看起来像这样

<?php

return [

    ...

    'disks' => [

				...

        's3' => [
            'driver' => 's3',
            'key' => env('AWS_ACCESS_KEY_ID'),
            'secret' => env('AWS_SECRET_ACCESS_KEY'),
            'region' => env('AWS_DEFAULT_REGION'),
            'bucket' => env('AWS_BUCKET'),
            'url' => env('AWS_URL'),
        ],

				// Add this entry
				env('S3_TOOLS_DISK_NAME', 's3-tools') => [
          'driver' => env('S3_TOOLS_DISK_NAME', 's3-tools'),
          'key' => env('AWS_ACCESS_KEY_ID'),
          'secret' => env('AWS_SECRET_ACCESS_KEY'),
          'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
          'bucket' => env('AWS_BUCKET'),
          'url' => env('AWS_URL'),
        ],
      ],
	...

用法

方法概要

这是 TL;DR 部分。以下是您使用 laravel-s3-tools 包可用的方法。每个方法都将在下面的示例中进行更详细的描述

获取指定对象的版本列表

可以通过以下方式检索和处理存储在 S3 中的对象的可用版本列表。返回的版本列表将根据最后修改日期按倒序排列。最新版本（最新版本）始终是返回数组中的第一个元素（0）。

$versions = Storage::disk('s3-tools')->getObjectVersions('myfile.png');

foreach($versions as $v)
{
	echo '<li> Version ID: ' . $v['versionId'];
	echo '<li> File Size: ' . $v['fileSize'] . ' bytes';
	echo '<li> Is Latest Version?: ' . $v['isLatest']; // Will be true or false (boolean)
	echo '<li> Date Modified: ' . $v['dateModified'];
	echo '<li> ----------------------------------------------';
}

上述代码的输出将类似于以下内容

- Version ID: WX6q0O9qkcAcqld3DidZo2m5z68uGKnn
- File Size: 132645 bytes
- Is Latest Version?: 1
- Date Modified: 2019-03-21T19:35:29+00:00
----------------------------------------------
- Version ID: nMw5IAmOPdMK0MR3eXtkSPVQTd18Vucd
- File Size: 3631 bytes
- Is Latest Version?:
- Date Modified: 2019-03-21T19:16:26+00:00
----------------------------------------------
...

检索对象的最新版本

要检索给定对象的最新版本，只需像往常一样使用 Storage 面具。以下是从 S3 中检索图像最新版本的示例。

// Fetch the latest version of the file from S3
$file = Storage::disk('s3-tools')->get('myfile.png');
	
// Show the image in the browser
return response($file)->header('Content-Type', 'image/png');

检索特定版本的对象

但是，与 Laravel 不同，它也可以用来指定您要检索的对象的特定版本。可以用来从 S3 中检索特定对象版本的 getObjectVersions() 返回的 versionId 字段。

// Fetch the image from S3
$versionId = 'fiWFsPPFwbvlGh37rB9IaZYkO4pzOgWGz';
$file = Storage::disk('s3-tools')->getVersion($versionId)->get('myfile.png');
	
// Show the image in the browser
return response($file)->header('Content-Type', 'image/png');

删除对象的最新版本

如果不指定特定版本，将删除对象的最新版本。

$result = Storage::disk('s3-tools')->delete('some/longer/S3/path/business-plan.pdf');

如果启用存储桶的版本控制，上述操作实际上不会“删除”S3中的文件。默认情况下，S3将为该版本的文件放置一个 DeleteMarker。但是，Amazon 会向您收取 DeleteMarker 存储的少量费用。要完全删除文件并确保没有 DeleteMarker，您需要像下面展示的那样删除文件的特定版本。

或者，您可以这样做来帮助管理 S3 中的 DeleteMarkers

• 登录到 S3 控制台
• 选择您的存储桶
• 打开属性
• 点击生命周期
• 创建一个规则集，在对象创建日期后 n 天永久删除

删除对象的特定版本

如果您指定了 versionId，您可以选择性地删除该对象特定的版本，假设它存在。此操作也不会留下 DeleteMarker - 可以将其视为“硬删除”操作。

$versionId = 'fiWFsPPFwbvlGh37rB9IaZYkO4pzOgWGz';
$result = Storage::disk('s3-tools')->getVersion($versionId)->delete('some/longer/S3/path/business-plan.pdf');

设置 AWS/S3 API 选项

有时，您可能需要为特定的请求提供额外的选项。每个 API 调用的选项都有在 Amazon 的 API 参考网站 上进行了良好的文档说明。例如，考虑这个请求，它与这个包中内置的 getVersion() 方法做相同的事情

$result = Storage::disk('s3-tools')->setOption('VersionId', $versionString)->get('myfile.png');

您还可以使用复数形式的 setOptions() 来传递选项数组

$options = [
	'VersionId' => 'fiWFsPPFwbvlGh37rB9IaZYkO4pzOgWGz',
	'IfModifiedSince' => '2 days ago'
];

$result = Storage::disk('s3-tools')->setOptions($options)->delete('myfile.png');

clearOption() 方法将重置特定选项，而 clearOptions() 方法将重置所有选项。如果您在进行到和从 S3 的复杂操作中遇到任何奇怪的问题，在发出某些 API 调用之前调用 clearOptions() 来重置可能是有益的。

// Retrieve a specific version of a file
$versionId = 'fiWFsPPFwbvlGh37rB9IaZYkO4pzOgWGz';
$file = Storage::disk('s3-tools')->setOption('VersionId', $versionId)->get('myfile.png');

// Clear out ll of our options
$file = Storage::disk('s3-tools')->clearOptions();

// or alternatively, just clear the 'VersionId' option
//$file = Storage::disk('s3-tools')->clearOption('VersionId');

// Get the latest version of another file ...
$file = Storage::disk('s3-tools')->get('myfile.png');

执行其他 Amazon S3 API 命令

使用command()方法，您可以执行任何其他S3 API调用，而且这些调用有很多。然而，您不仅需要传递所有合适的选项，还需要解析响应。所有通过此方法返回的响应都是以原始格式发送给您的。从某种意义上说，这有点多余，因为您可以直接使用官方S3 API来执行它们，但我还是在这里包含它，以便在您决定使用此包进行其他操作时提供一种一致性方法。

请考虑以下示例，它与该包内置的getObjectVersions()方法执行相同的功能。

$result = Storage::disk('s3-tools')->command('ListObjectVersions', [
	'Prefix' => 'some/longer/S3/path/business-plan.pdf'
]);

这是上面相同的命令，但使用不同的存储桶名称。

$result = Storage::disk('s3-tools')->command('ListObjectVersions', [
	'Bucket' => 'MyBucketName',
	'Prefix' => 'some/longer/S3/path/business-plan.pdf'
]);

以下是一个创建新S3存储桶的示例。记住，S3中的存储桶名称必须符合DNS命名约定，因此：

• 不应包含大写字母。
• 不应包含下划线。
• 长度应在3到63个字符之间。
• 不应以破折号结尾。
• 不能包含两个相邻的点。
• 不能在点旁边使用破折号（例如，“my-.bucket.com”和“my.-bucket”是无效的）。

$result = Storage::disk('s3-tools')->command('CreateBucket', [
	'Bucket' => 'my-terrific-bucket-name',
	'ACL' => 'private'
]);

以下是一个最终示例。在单个API调用中删除多个对象。在这个示例中，我们删除了myfile.png和business-plan.pdf的最新版本，以及一个虚构电子表格的特定版本。

$result = Storage::disk('s3-tools')->command('DeleteObjects', [
	'Delete' => [
		[ 'Key' => 'myfile.png' ],
		[ 'Key' => 'some/longer/S3/path/business-plan.pdf' ],
		[ 
			'Key' => 'some/longer/S3/path/financial-planning-spreadsheet.xlsx', 
			'VersionId' => 'fiWFsPPFwbvlGh37rB9IaZYkO4pzOgWGz'
		]
	]
]);

Storage::command使用说明

• 当使用Storage::command方法时，唯一默认的“选项”值是Bucket... 如果没有直接传递存储桶名称，它将默认为您的.env文件中AWS_BUCKET的值。

更新日志

有关最近更改的更多信息，请参阅更新日志。

贡献

有关详细信息，请参阅贡献指南。

安全性

如果您发现任何安全相关的问题，请通过电子邮件scott@incurs.us联系，而不是使用问题跟踪器。

鸣谢

• Scott Burkett

许可协议

MIT许可协议（MIT）。有关更多信息，请参阅许可文件。