【PHP8.x】IteratorAggregate::getIterator()メソッドの使い方

Copy
1<?php
2
3require 'vendor/autoload.php'; // Composerのオートロードファイルを読み込みます
4
5use Aws\S3\S3Client;
6use IteratorAggregate;
7use Traversable;
8
9/**
10 * S3バケット内のオブジェクト一覧を、イテレータとして提供するクラス。
11 * IteratorAggregateインターフェースを実装することで、foreachループで直接オブジェクトを反復処理できます。
12 *
13 * システムエンジニアを目指す初心者の方へ：
14 * このクラスは、S3バケット内の大量のファイル（オブジェクト）を、一度にすべてメモリに読み込むことなく、
15 * 必要に応じて順次処理するための効率的な方法を示しています。
16 * `getIterator()` メソッドは、`yield` キーワードを使用して「ジェネレータ」を返し、
17 * これによりメモリ使用量を抑えながら反復処理を実現します。
18 */
19class S3ObjectList implements IteratorAggregate
20{
21    private S3Client $s3Client;
22    private string $bucketName;
23
24    /**
25     * S3ObjectListの新しいインスタンスを生成します。
26     *
27     * @param S3Client $s3Client S3操作に使用するAWS S3クライアントインスタンス。
28     * @param string $bucketName オブジェクト一覧を取得したいS3バケットの名前。
29     */
30    public function __construct(S3Client $s3Client, string $bucketName)
31    {
32        $this->s3Client = $s3Client;
33        $this->bucketName = $bucketName;
34    }
35
36    /**
37     * S3バケット内のオブジェクトを反復処理するためのイテレータを返します。
38     * IteratorAggregateインターフェースの必須メソッドです。
39     *
40     * ここではPHPのジェネレータ機能 (`yield`) を利用して、
41     * S3 APIのページネーション結果を効率的にイテレータとして提供します。
42     *
43     * @return Traversable S3オブジェクトのキーやサイズなどの情報を含むイテレータ。
44     *                     各要素は連想配列（例: ['Key' => 'path/to/file.txt', 'Size' => 1234]）です。
45     */
46    public function getIterator(): Traversable
47    {
48        // AWS SDKのgetPaginatorを使用して、S3のListObjectsV2 APIの結果をページ単位で取得します。
49        // ListObjectsV2は、S3バケット内のオブジェクトを効率的にリストするためのAPIです。
50        $paginator = $this->s3Client->getPaginator('ListObjectsV2', [
51            'Bucket' => $this->bucketName,
52        ]);
53
54        // Paginatorは複数の「ページ」（オブジェクトのグループ）を返します。
55        // 各ページから個々のオブジェクトを取り出してyieldで返します。
56        foreach ($paginator as $page) {
57            // 'Contents' キーにオブジェクトのリストが含まれています。
58            if (isset($page['Contents'])) {
59                foreach ($page['Contents'] as $object) {
60                    // `yield` を使うことで、このメソッドはジェネレータとして動作します。
61                    // foreachループで各オブジェクトが必要とされたときにS3から取得され、
62                    // メモリにロードされるのは一度に1つのオブジェクト情報のみとなります。
63                    yield $object;
64                }
65            }
66        }
67    }
68}
69
70// ----------------------------------------------------------------------------------------------------
71// 以下は上記のS3ObjectListクラスの利用例です。
72// ご自身のAWS認証情報とS3バケット名に置き換えて実行してください。
73// ----------------------------------------------------------------------------------------------------
74
75try {
76    // AWS S3Clientを初期化します。
77    // 本番環境では、認証情報は環境変数、IAMロール、または共有認証情報ファイルから取得することが推奨されます。
78    // アクセスキーとシークレットキーを直接コードに記述することはセキュリティ上のリスクがあるため、
79    // 開発/テスト目的以外では避けてください。
80    $s3Client = new S3Client([
81        'version'     => 'latest',             // 使用するS3 APIのバージョン
82        'region'      => 'ap-northeast-1',     // S3バケットが存在するリージョン (例: 東京リージョン)
83        'credentials' => [
84            'key'    => 'YOUR_AWS_ACCESS_KEY_ID',     // あなたのAWSアクセスキーIDに置き換えてください
85            'secret' => 'YOUR_AWS_SECRET_ACCESS_KEY', // あなたのAWSシークレットアクセスキーに置き換えてください
86        ],
87        // オプション: ローカル開発環境でMinIOなどのS3互換ストレージを使用する場合
88        // 'endpoint'    => 'http://localhost:9000',
89        // 'use_path_style_endpoint' => true,
90    ]);
91
92    $bucketName = 'your-example-bucket'; // 実際に存在するS3バケット名に置き換えてください
93
94    // S3ObjectListクラスのインスタンスを作成します。
95    // これでS3バケット内のオブジェクトを反復処理する準備ができました。
96    $s3ObjectList = new S3ObjectList($s3Client, $bucketName);
97
98    echo "S3バケット '{$bucketName}' 内のオブジェクト一覧:\n";
99    $count = 0;
100
101    // S3ObjectListインスタンスをforeachループで直接反復処理します。
102    // このとき、内部でgetIterator()メソッドが呼び出され、
103    // S3からオブジェクト情報が順次取得されます。
104    foreach ($s3ObjectList as $object) {
105        $count++;
106        echo "  - キー: {$object['Key']} (サイズ: {$object['Size']} バイト, 最終更新: {$object['LastModified']})\n";
107        // 例として最初の10個のオブジェクトだけを表示し、大量出力でターミナルが埋まるのを防ぎます
108        if ($count >= 10) {
109            echo "  ...\n";
110            break;
111        }
112    }
113    if ($count == 0) {
114        echo "  (オブジェクトが見つかりませんでした。)\n";
115    }
116
117} catch (\Aws\Exception\AwsException $e) {
118    // AWS関連のエラーが発生した場合の処理
119    echo "AWSエラーが発生しました: " . $e->getMessage() . "\n";
120    if ($e->getResponse()) {
121        echo "  HTTPステータス: " . $e->getResponse()->getStatusCode() . "\n";
122        echo "  エラーコード: " . $e->getAwsErrorCode() . "\n";
123    }
124} catch (\Exception $e) {
125    // その他の予期せぬエラーが発生した場合の処理
126    echo "一般エラーが発生しました: " . $e->getMessage() . "\n";
127}
128
129?>

このサンプルコードは、PHPのIteratorAggregateインターフェースとgetIteratorメソッドの利用方法を具体的に示しています。IteratorAggregateを実装するクラスは、getIteratorメソッドを必ず定義し、そのメソッドがTraversable型のイテレータを返すことで、クラスのインスタンスをforeachループで直接反復処理できるようになります。

S3ObjectListクラスは、AWS S3バケット内のオブジェクト一覧を効率的に取得するため、このgetIteratorメソッドを実装しています。メソッド内では、PHPのyieldキーワードを利用した「ジェネレータ」機能が活用されています。ジェネレータは、S3からの大量のオブジェクト情報を一度にメモリに読み込むことなく、必要に応じて少しずつデータを生成し提供できるため、メモリ使用量を抑えながら大規模なデータセットを処理するのに非常に有効です。

getIteratorメソッドは引数を一切取りません。戻り値はTraversable型で、これはforeachループで反復可能なあらゆるオブジェクトの総称です。この実装では、yieldによって生成されるGeneratorオブジェクトがTraversableとして扱われます。これにより、S3バケット内の各オブジェクト情報が、あたかも配列のように順番に取り出せるようになります。