AWS SDK for PHP バージョン 3 での Amazon S3 ストリームラッパー - AWS SDK for PHP

AWS SDK for PHP バージョン 3 での Amazon S3 ストリームラッパー

Amazon S3 ストリームラッパーにより、組み込み PHP 関数 file_get_contentsfopencopyrenameunlinkmkdirrmdir などを使用して Amazon S3 に対してデータの保存および取得ができます。

使用するために Amazon S3 ストリームラッパーを登録する必要があります。

$client = new Aws\S3\S3Client([/** options **/]); // Register the stream wrapper from an S3Client object $client->registerStreamWrapper();

これにより、s3:// プロトコルを使用して Amazon S3 に保存されたバケットとオブジェクトにアクセスできます。Amazon S3 ストリームラッパーは、バケット名を含む文字列を受け入れます。この名前にフォワードスラッシュとオプションのオブジェクトキーまたはプレフィックスが続きます (s3://<bucket>[/<key-or-prefix>])。

注記

ストリームラッパーは少なくともユーザーの読み取りアクセス許可があるオブジェクトとバケットを操作するために設計されています。つまり、ユーザーが操作する必要がある任意のオブジェクトで ListBucket、任意のバケットで GetObject を実行するアクセス許可がユーザーに必要です。このアクセス許可がユーザーにないユースケースでは、S3 クライアントオペレーションを直接使用することをお勧めします。

データのダウンロード

file_get_contents を使用して、オブジェクトのコンテンツを取得できます。ただし、この関数では、オブジェクトのコンテンツ全体をメモリにロードすることに注意してください。

// Download the body of the "key" object in the "bucket" bucket $data = file_get_contents('s3://bucket/key');

大きいファイルを操作するとき、または Amazon S3 からデータをストリーミングする必要がある場合は、fopen() を使用します。

// Open a stream in read-only mode if ($stream = fopen('s3://bucket/key', 'r')) { // While the stream is still open while (!feof($stream)) { // Read 1,024 bytes from the stream echo fread($stream, 1024); } // Be sure to close the stream resource when you're done with it fclose($stream); }
注記

ファイルの書き込みエラーは fflush の呼び出しが行われた場合にのみ返されます。これらのエラーはフラッシュされていない fclose が呼び出されたときに返されません。fclose の戻り値は、ストリームを閉じる場合は true です。内部 fflush の応答に何らかエラーがあっても関係ありません。これらのエラーは file_put_contents 呼び出し時にも返されません。これは PHP 実装の仕様のためです。

シーク可能なストリームのオープン

「r」モードで開いたストリームは、ストリームからデータを読み取ることのみ可能です。さらに、デフォルトではシーク可能ではありません。これは、真にストリーミング方式でデータを Amazon S3 からダウンロードできるようにするためです。ここで、事前読み取りバイトをメモリにバッファする必要はありません。ストリームをシーク可能にする必要がある場合は、seekable を関数のストリームコンテキストオプションに渡すことができます。

$context = stream_context_create([ 's3' => ['seekable' => true] ]); if ($stream = fopen('s3://bucket/key', 'r', false, $context)) { // Read bytes from the stream fread($stream, 1024); // Seek back to the beginning of the stream fseek($stream, 0); // Read the same bytes that were previously read fread($stream, 1024); fclose($stream); }

シーク可能なストリームをオープンすると、事前に読み込んだバイト数のシークが可能になります。リモートサーバーからまだ読み取っていないバイト数までスキップすることはできません。事前に読み取ったデータの記憶を許可するには、ストリームデコレータを使用して、データを PHP の一時ストリームにバッファします。キャッシュされたデータの量が 2 MB を超えた場合、一時ストリーム内のデータはメモリからディスクに転送されます。seekable ストリームコンテキスト設定を使用して、Amazon S3 から大きなファイルをダウンロードする際は、このことを念頭に置いてください。

データのアップロード

file_put_contents() を使用して Amazon S3 にデータをアップロードすることができます。

file_put_contents('s3://bucket/key', 'Hello!');

fopen() で「w」、「x」、または「a」ストリームアクセスモードを使用したストリーミングデータによりさらに大きなファイルをアップロードできます。Amazon S3 ストリームラッパーは、同時読み取りおよび書き込みストリーム (「r+」、「w+」など) をサポートしていません。これは、HTTP プロトコルが同時読み取りおよび書き込みを許可しないためです。

$stream = fopen('s3://bucket/key', 'w'); fwrite($stream, 'Hello!'); fclose($stream);
注記

Amazon S3 ではリクエストのペイロードが送信される前に Content-Length ヘッダーを指定する必要があります。したがって、PutObject オペレーションでアップロード対象のデータは、ストリームがフラッシュまたはクローズされるまで、PHP の一時ストリームを使用して内部にバッファされます。

注記

ファイルの書き込みエラーは fflush の呼び出しが行われた場合にのみ返されます。これらのエラーはフラッシュされていない fclose が呼び出されたときに返されません。fclose の戻り値は、ストリームを閉じる場合は true です。内部 fflush の応答に何らかエラーがあっても関係ありません。これらのエラーは file_put_contents 呼び出し時にも返されません。これは PHP 実装の仕様のためです。

fopen モード

PHP の fopen() 関数では $mode オプションを指定する必要があります。モードオプションでは、データをストリームに対して読み取りや書き込みを行うかどうか、ストリームを開くときに、ファイルが存在しているかどうかを指定します。Amazon S3 ストリームラッパーは次のモードをサポートしています。

r

ファイルの存在を前提にしている読み取り専用ストリーム。

w

書き込みのみのストリーム。このファイルが存在している場合、上書きされます。

a

書き込みのみのストリーム。ファイルがすでに存在する場合は、一時的なストリームにダウンロードされ、ストリームへの書き込みが事前にアップロードされたデータに追加されます。

x

書き込みのみのストリーム。エラーは、ファイルが存在しない場合に発生します。

その他のオブジェクト関数

ストリームラッパーにより、さまざまな組み込み PHP 関数は Amazon S3 などのカスタムシステムで使用できます。ここに示すのは、Amazon S3 に格納されるオブジェクトでユーザーが実行することができる Amazon S3 ストリームラッパー関数の一部です。

unlink()

バケットから 1 つのオブジェクトを削除します。

// Delete an object from a bucket unlink('s3://bucket/key');

DeleteObject オペレーションに使用可能なオプションで渡すことができ、オブジェクトが削除される方法を変更できます (特定のオブジェクトバージョンの指定など)。

// Delete a specific version of an object from a bucket unlink('s3://bucket/key', stream_context_create([ 's3' => ['VersionId' => '123'] ]);

filesize()

オブジェクトのサイズを取得します。

// Get the Content-Length of an object $size = filesize('s3://bucket/key', );

is_file()

URL がファイルかどうかを確認します。

if (is_file('s3://bucket/key')) { echo 'It is a file!'; }

file_exists()

オブジェクトが存在するかどうかを確認します。

if (file_exists('s3://bucket/key')) { echo 'It exists!'; }

filetype()

URL がファイルまたはバケット (dir) にマッピングされるかどうかを確認します。

file()

行の配列にあるオブジェクトの内容をロードします。GetObject オペレーションに使用可能なオプションを渡して、ファイルのダウンロード方法を変更できます。

filemtime()

オブジェクトが最後に変更された日付を取得します。

オブジェクトの名前を()

オブジェクトをコピーし、元のオブジェクトを削除することで、オブジェクトの名前を変更します。CopyObject および DeleteObject オペレーションに使用可能なオプションをストリームコンテキストパラメーターに渡すことができ、オブジェクトのコピーおよび削除方法を変更できます。

注記

通常、copy は Amazon S3 ストリームラッパーとともに使用できますが、PHP での copy 関数の内部処理のために一部のエラーが適切に報告されないことがあります。代わりに AwsS3ObjectCopier のインスタンスを使用することをお勧めします。

バケットの使用

Amazon S3 バケットを変更して参照できます。使用するファイルシステムのディレクトリの変更とトラバーサルを PHP で許可する方法と同様です。

以下にバケットの作成の例を挙げます。

mkdir('s3://bucket');

ストリームにコンテキストオプションを mkdir() メソッドに渡して、バケットの作成方法を変更できます。CreateBucket オペレーションで利用可能なパラメーターを使用します。

// Create a bucket in the EU (Ireland) Region mkdir('s3://bucket', stream_context_create([ 's3' => ['LocationConstraint' => 'eu-west-1'] ]);

rmdir() 関数を使用してバケットを削除できます。

// Delete a bucket rmdir('s3://bucket');
注記

バケットは、空である場合に限り、削除できます。

バケットの内容の一覧表示

opendir()readdir()rewinddir()closedir() PHP 関数を Amazon S3 ストリームラッパーで使用して、バケットの内容を検討します。ListObjects オペレーションで使用できるパラメーターを、opendir() 関数に対するカスタムストリームコンテキストオプションとして渡し、オブジェクトを一覧表示する方法を変更できます。

$dir = "s3://bucket/"; if (is_dir($dir) && ($dh = opendir($dir))) { while (($file = readdir($dh)) !== false) { echo "filename: {$file} : filetype: " . filetype($dir . $file) . "\n"; } closedir($dh); }

PHP の RecursiveDirectoryIterator を使用し、バケット内のプレフィックスと各オブジェクトを再帰的にリストすることができます。

$dir = 's3://bucket'; $iterator = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($dir)); foreach ($iterator as $file) { echo $file->getType() . ': ' . $file . "\n"; }

少ない HTTP リクエストで再帰的に、バケットの内容をリストする別の方法は、Aws\recursive_dir_iterator($path, $context = null) 関数を使用します。

<?php require 'vendor/autoload.php'; $iter = Aws\recursive_dir_iterator('s3://bucket/key'); foreach ($iter as $filename) { echo $filename . "\n"; }

ストリームコンテキストオプション

ストリームラッパーで使用されるクライアント、またはカスタムストリームコンテキストオプションを渡すことによって、バケットやキーに関する事前にロードされた情報をキャッシュするために使用できるキャッシュをカスタマイズできます。

ストリームラッパーはオペレーションごとに次のストリームコンテキストオプションをサポートしています。

client

コマンドを実行するために使用する Aws\AwsClientInterface オブジェクトです。

cache

以前に取得したファイル統計情報をキャッシュするために使用する Aws\CacheInterface のインスタンスです。デフォルトでは、ストリームラッパーはインメモリ LRU キャッシュを使用します。