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

buildFromIteratorメソッドは、PharDataオブジェクトが表すtarやzipなどのデータアーカイブを、イテレータから受け取ったファイル情報に基づいて効率的に構築または更新するメソッドです。

このメソッドは、指定されたイテレータが提供するファイルパスとコンテンツの情報を利用して、現在のアーカイブに複数のファイルを一度に追加したり、新しいアーカイブを作成したりするために使用されます。イテレータは、アーカイブに含めたいファイルやディレクトリのリストと、それぞれのファイルの内容を順番に処理するための汎用的な仕組みです。これにより、手動でファイルを一つずつ追加する手間を省き、複雑なディレクトリ構造を持つ大量のファイルも容易に扱えます。

オプションの第二引数として $baseDirectory を指定できます。これは、アーカイブ内でファイルパスがどのように表現されるかを決定する基点となるディレクトリパスです。例えば、イテレータが /var/www/html/project/src/file.php というパスを返しても、$baseDirectory に /var/www/html/project を指定すれば、アーカイブ内では src/file.php として格納されます。これにより、実際のファイルシステム上のパスとアーカイブ内のパスを簡潔にマッピングできます。

メソッドが成功すると、アーカイブに追加された全てのファイルのパス（$baseDirectory が指定されている場合はそれに基づいた相対パス）を含む文字列の配列を返します。この機能は、ウェブアプリケーションのデプロイメントパッケージやソフトウェアのリリースアーカイブなど、特定のディレクトリ構造を持つ多数のファイルを効率的にパッケージングする必要がある場面で非常に役立ちます。

Copy
1<?php
2
3// PharData クラスのインスタンスを作成します。
4// 例: 新しいTAR形式のアーカイブ 'my_archive.tar' を作成する場合
5$pharData = new PharData('my_archive.tar');
6
7// アーカイブに追加するファイルのリストを提供するイテレータを作成します。
8// この例では、指定したディレクトリとそのサブディレクトリ内のすべてのファイルを走査するイテレータを作成しています。
9$iterator = new RecursiveIteratorIterator(
10    new RecursiveDirectoryIterator(
11        'path/to/source/directory', // アーカイブに含めるファイルの存在するディレクトリ
12        FilesystemIterator::SKIP_DOTS // '.' と '..' をスキップします
13    ),
14    RecursiveIteratorIterator::LEAVES_ONLY // ディレクトリ自体ではなくファイルのみを返します
15);
16
17// buildFromIterator メソッドを呼び出し、イテレータからアーカイブにファイルを追加します。
18$addedFiles = $pharData->buildFromIterator(
19    $iterator,                       // Iterator $iterator: ファイル名（キー）とファイルのパス（値）を返すイテレータ
20    'path/to/source/directory/'      // ?string $baseDirectory: (オプション) アーカイブ内のパスから取り除かれるパスプレフィックス
21    // '/\.txt$/i'                   // ?string $regex: (オプション) イテレータをフィルタリングするための正規表現パターン
22);
23
24// 成功した場合、$addedFiles にはアーカイブに追加されたファイルの相対パスの配列が返されます。
25
26?>

Traversable $iterator, ?string $baseDirectory = null

• Traversable $iterator: Pharアーカイブに含めるファイルやディレクトリを列挙するイテレータブルオブジェクト
• ?string $baseDirectory = null: $iterator で指定されたパスの基準となるディレクトリ。指定しない場合はカレントディレクトリが基準となる

array|bool

PharData::buildFromIterator メソッドは、指定されたイテレータからpharアーカイブを構築します。処理が成功した場合は、アーカイブに追加されたエントリのパス名を要素とする配列を返します。処理中にエラーが発生した場合は、false を返します。