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

Amazon S3 ストリームラッパーにより、組み込み PHP 関数 file_get_contents、fopen、copy、rename、unlink、mkdir、rmdir などを使用して 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>])。

データをダウンロードする

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);
}

シーク可能なストリームを開く

「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);

fopen モード

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

Amazon S3 ストリームラッパーは、Amazon S3 オブジェクトをターゲットとするストリームで次のモードをサポートしています。

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

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

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

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

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

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

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

バケットとフォルダの操作

mkdir() を使用してバケットを操作する

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

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

mkdir('s3://my-bucket');

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

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

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

// Delete a bucket
rmdir('s3://my-bucket);

mkdir() を使用してフォルダを操作します。

バケットを作成したら、mkdir() を使用して、ファイルシステムのフォルダのようにフォルダとして機能するオブジェクトを作成できます。

次のコードスニペットは、「my-folder」という名前のフォルダオブジェクトを「my-bucket」という名前の既存のバケットに追加します。フォワードスラッシュ (/) 文字を使用して、フォルダオブジェクト名をバケット名およびその他のフォルダ名と区切ります。

mkdir('s3://my-bucket/my-folder')

2023 年 4 月以降の権限変更に関する前述の注意事項は、フォルダーオブジェクトを作成するときにも関係します。このブログ投稿には、必要に応じて権限を調整する方法についての情報が記載されています。

次のスニペットに示すように、rmdir() 関数を使用して空のフォルダオブジェクトを削除します。

rmdir('s3://my-bucket/my-folder')

バケットの内容を一覧表示する

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";
}

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

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

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