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

buildFromIteratorメソッドは、PHPアプリケーションの配布形式であるPharアーカイブを生成する際に、ファイルやディレクトリのリストをイテレータ（反復子）から効率的に読み込んでアーカイブに追加するメソッドです。このメソッドは、Pharクラスの一部として提供されており、大量のファイルを含むプロジェクトを単一の実行可能な.pharファイルにまとめるために利用されます。

このメソッドを使用することで、開発者はIteratorインターフェースを実装した任意のオブジェクトを使い、柔軟な条件で選択されたファイル群をアーカイブに含めることが可能になります。例えば、ファイルシステム上の特定のディレクトリ構造に縛られず、カスタムロジックで選択されたファイル（特定の拡張子を持つファイルのみ、あるいは特定の条件を満たすファイルなど）を効率的にPharアーカイブに追加する場合に非常に有効です。

第一引数には、アーカイブに追加するファイルパスのリストを返すIteratorオブジェクトを指定します。このイテレータは、アーカイブに含めるファイルパスを、内部パスとして適切に解決できるように提供する必要があります。オプションの第二引数には、アーカイブ内のファイルパスに適用するプレフィックスを指定でき、これによりアーカイブ内のディレクトリ構造を柔軟に調整できます。このメソッドを利用することで、PHPプロジェクトの配布とデプロイを簡素化し、効率的に管理することが可能になります。

Copy
1<?php
2
3// Pharオブジェクトのインスタンス化
4// 'my_archive.phar' は作成するPharアーカイブのファイル名です。
5$phar = new Phar('my_archive.phar');
6
7// アーカイブに追加するファイルの内容を保持するイテレータを準備します。
8// キーはアーカイブ内でのファイルのパス、値はファイルの内容（文字列）です。
9// ArrayIteratorはTraversableインターフェースを実装しており、Phar::buildFromIteratorに渡すことができます。
10$fileIterator = new ArrayIterator([
11    'path/in/archive/document.txt' => 'This is the content of document.txt.',
12    'another_directory/image.jpg' => 'Binary content for an image file...', // バイナリデータも可
13    'log.txt' => 'Log entry 1: Error occurred. Log entry 2: Success.',
14]);
15
16// Phar::buildFromIterator メソッドを呼び出して、イテレータからPharアーカイブを構築します。
17//
18// 引数:
19// 1. $iterator (Traversable): ファイルのキーと値を含むイテレータ。必須引数です。
20// 2. $baseDirectory (?string): オプション。アーカイブにファイルを追加する際の基準ディレクトリ。
21//    nullまたは省略された場合、イテレータ内のパスは現在の作業ディレクトリからの相対パスとして扱われます。
22// 3. $options (?array): オプション。その他の設定（例: Phar::compressAllFiles）。
23//
24// 戻り値:
25// 追加されたすべてのファイルのリストを連想配列として返します。
26// キーはアーカイブ内のファイル名、値は実際のファイルパスです。
27$addedFiles = $phar->buildFromIterator($fileIterator);
28
29// $addedFiles には、アーカイブに追加されたファイルの情報が格納されます。
30// 例: [
31//   'path/in/archive/document.txt' => 'phar://my_archive.phar/path/in/archive/document.txt',
32//   'another_directory/image.jpg' => 'phar://my_archive.phar/another_directory/image.jpg',
33//   'log.txt' => 'phar://my_archive.phar/log.txt'
34// ]
35

Traversable $iterator, ?string $baseDirectory = null

• Traversable $iterator:pharアーカイブに含めるファイルやディレクトリのパスを順に取得できるイテレーターオブジェクト
• ?string $baseDirectory = null:pharアーカイブのルートディレクトリからの相対パスを指定する文字列。指定しない場合はpharアーカイブのルートが基準となる

array

Phar::buildFromIteratorメソッドは、Iteratorから生成されたPharアーカイブ内に含まれるファイルパスの配列を返します。