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

Copy
1<?php
2
3// 実行前に、php.ini で 'phar.readonly = 0' が設定されていることを確認してください。
4// これは Phar アーカイブを作成・変更するために必要です。
5// 通常、CLI 版 PHP のデフォルト設定は 'phar.readonly = 0' です。
6
7// 一時的なアーカイブファイル名
8$archiveFileName = 'example_archive.tar';
9$archivePath = __DIR__ . '/' . $archiveFileName;
10
11// 作業ディレクトリとサンプルファイルのパス
12$tempDir = __DIR__ . '/temp_archive_contents';
13$file1Path = $tempDir . '/file1.txt';
14$file2Path = $tempDir . '/file2.txt';
15$subDirPath = $tempDir . '/subdir';
16$file3Path = $subDirPath . '/file3.txt';
17
18/**
19 * サンプルコードで使用する一時ファイルとディレクトリをクリーンアップする関数。
20 *
21 * @param string $archivePath アーカイブファイルのパス
22 * @param string $tempDir 一時ディレクトリのパス
23 */
24function cleanup(string $archivePath, string $tempDir): void
25{
26    // アーカイブファイルが存在すれば削除
27    if (file_exists($archivePath)) {
28        unlink($archivePath);
29        // echo "アーカイブ '{$archivePath}' を削除しました。\n"; // デバッグ用
30    }
31
32    // 一時ディレクトリが存在すれば、その内容とディレクトリ自体を削除
33    if (is_dir($tempDir)) {
34        // サブディレクトリ内のファイルを削除し、サブディレクトリを削除
35        if (is_dir($subDirPath = $tempDir . '/subdir')) {
36            foreach (glob($subDirPath . '/*') as $item) {
37                if (is_file($item)) {
38                    unlink($item);
39                }
40            }
41            rmdir($subDirPath);
42        }
43        // メインディレクトリ内のファイルを削除
44        foreach (glob($tempDir . '/*') as $item) {
45            if (is_file($item)) {
46                unlink($item);
47            }
48        }
49        rmdir($tempDir);
50        // echo "一時ディレクトリ '{$tempDir}' を削除しました。\n"; // デバッグ用
51    }
52}
53
54try {
55    // -----------------------------------------------------
56    // 前処理：既存の一時ファイルとディレクトリをクリーンアップ
57    // -----------------------------------------------------
58    cleanup($archivePath, $tempDir);
59
60    // -----------------------------------------------------
61    // 1. サンプルアーカイブを作成するための準備
62    // -----------------------------------------------------
63    // 作業ディレクトリを作成 (必要であれば再帰的に)
64    if (!is_dir($tempDir)) {
65        mkdir($tempDir, 0777, true);
66    }
67    if (!is_dir($subDirPath)) {
68        mkdir($subDirPath, 0777, true);
69    }
70
71    // サンプルファイルを作成
72    file_put_contents($file1Path, 'これはファイル1の内容です。');
73    file_put_contents($file2Path, 'これはファイル2の内容です。');
74    file_put_contents($file3Path, 'これはサブディレクトリ内のファイル3の内容です。');
75
76    echo "サンプルファイルを作成しました。\n";
77
78    // -----------------------------------------------------
79    // 2. PharDataオブジェクトを作成し、ファイルをアーカイブに追加
80    // -----------------------------------------------------
81    // PharData クラスは、.tar, .zip, .phar などのデータアーカイブを扱えます。
82    // 第1引数に作成するアーカイブファイルのパスを指定します。
83    $pharData = new PharData($archivePath);
84
85    // アーカイブに個々のファイルを追加します。
86    // 第1引数はファイルシステムの元のファイルのパス、
87    // 第2引数はアーカイブ内でのファイルパスです。
88    $pharData->addFile($file1Path, 'file1.txt');
89    $pharData->addFile($file2Path, 'file2.txt');
90    $pharData->addFile($file3Path, 'subdir/file3.txt');
91
92    echo "アーカイブ '{$archiveFileName}' にサンプルファイルを追加しました。\n\n";
93
94    // -----------------------------------------------------
95    // 3. getChildren() メソッドを使ってアーカイブの内容を列挙
96    // -----------------------------------------------------
97    echo "--- アーカイブ '{$archiveFileName}' の内容を列挙 ---\n";
98
99    // getChildren() メソッドは、アーカイブ内の各エントリ（ファイルやディレクトリ）を
100    // PharFileInfo オブジェクトとして提供するイテレータを返します。
101    // このメソッドに引数はありません。
102    //
103    // プログラミング言語リファレンス情報では戻り値が 'PharData|null' と記載されていますが、
104    // PHP公式ドキュメントでは RecursiveDirectoryIterator のインスタンスが返されると定義されており、
105    // そのイテレータの要素は PharFileInfo オブジェクトです。
106    // 通常、null が返されるケースは稀ですが、リファレンス情報に基づきnullチェックを行います。
107    $children = $pharData->getChildren();
108
109    if ($children === null) {
110        echo "  アーカイブが空であるか、内容の取得に失敗しました。\n";
111    } else {
112        foreach ($children as $name => $fileInfo) {
113            // $fileInfo は PharFileInfo オブジェクトです。
114            // getName() でアーカイブ内でのファイルパスを取得できます。
115            // isDir() でそれがディレクトリかどうかを確認できます。
116            $type = $fileInfo->isDir() ? 'Directory' : 'File';
117            echo "  - {$fileInfo->getName()} ({$type})\n";
118        }
119    }
120    echo "---------------------------------------------------\n";
121
122} catch (PharException $e) {
123    // Phar 拡張機能に関する操作中に発生したエラーを捕捉します。
124    echo "Phar 操作中にエラーが発生しました: " . $e->getMessage() . "\n";
125    echo "ヒント: php.ini で 'phar.readonly = 0' が設定されているか確認してください。\n";
126} catch (Exception $e) {
127    // その他の予期せぬエラーを捕捉します。
128    echo "予期せぬエラーが発生しました: " . $e->getMessage() . "\n";
129} finally {
130    // -----------------------------------------------------
131    // 後処理：作成した一時ファイルとディレクトリをクリーンアップ
132    // -----------------------------------------------------
133    cleanup($archivePath, $tempDir);
134    echo "\n一時ファイルとディレクトリをクリーンアップしました。\n";
135}
136
137?>

PHPのPharDataクラスに属するgetChildren()メソッドは、.tarや.zipなどのデータアーカイブ（PharDataオブジェクト）に含まれるファイルやディレクトリを列挙するために使用します。このメソッドは引数を必要としません。戻り値はPharDataオブジェクトかnullです。通常、アーカイブ内の各エントリをPharFileInfoオブジェクトとして順次提供するイテレータが返され、これをforeachループで処理することで、アーカイブの中身を一つずつ確認できます。もしアーカイブが空であるなど、内容の取得に失敗した場合はnullが返される可能性があります。

サンプルコードでは、まずPharDataオブジェクトを作成し、いくつかのファイルをアーカイブに追加しています。その後、$pharData->getChildren()を呼び出し、取得した結果をforeachループで反復処理しています。ループ内では、各エントリがPharFileInfoオブジェクトとして扱われ、getName()でアーカイブ内のパスを取得したり、isDir()でそれがディレクトリかファイルかを判別したりして、アーカイブの内容を詳細に表示しています。このようにgetChildren()メソッドを活用することで、データアーカイブの構造を手軽に確認し、その内容を操作するための基盤とすることができます。アーカイブの作成や変更を行う際は、php.iniでphar.readonly = 0が設定されていることを必ず確認してください。

Copy
1<?php declare(strict_types=1);
2
3/**
4 * Demonstrates how to use PharData::getChildren() to list the contents of a directory within an archive.
5 *
6 * This function creates a temporary .tar archive with a nested directory structure.
7 * It then opens the archive to find a specific directory entry ('parent_dir')
8 * and uses the getChildren() method on that entry to list its immediate contents.
9 */
10function demonstratePharDataGetChildren(): void
11{
12    // Define names for the temporary archive and its contents
13    $archiveName = 'nested_archive.tar';
14    $parentDir = 'parent_dir';
15    $fileA = $parentDir . '/file_a.txt';
16    $childDir = $parentDir . '/child_dir';
17    $fileB = $childDir . '/file_b.txt';
18
19    // --- Step 1: Create dummy files and directories on the filesystem ---
20    echo "Creating dummy files and directories on disk...\n";
21    mkdir($parentDir);
22    file_put_contents($fileA, 'This is content for file_a.txt.');
23    mkdir($childDir);
24    file_put_contents($fileB, 'This is content for file_b.txt.');
25
26    // --- Step 2: Create a new PharData archive and add files ---
27    try {
28        echo "Creating PharData archive: {$archiveName}\n";
29        // Create a new .tar archive in write mode
30        $phar = new PharData($archiveName, 0, null, Phar::TAR);
31
32        // Add files to the archive, specifying their paths within the archive
33        // This implicitly creates directory entries within the archive structure.
34        $phar->addFile($fileA, $parentDir . '/file_a.txt');
35        $phar->addFile($fileB, $childDir . '/file_b.txt');
36
37        echo "Archive created successfully.\n";
38    } catch (PharException $e) {
39        echo "Error creating PharData archive: " . $e->getMessage() . "\n";
40        // Clean up temporary files before exiting on error
41        @unlink($fileA);
42        @unlink($fileB);
43        @rmdir($childDir);
44        @rmdir($parentDir);
45        return;
46    }
47
48    // --- Step 3: Open the archive for reading and demonstrate getChildren() ---
49    echo "\nDemonstrating PharData::getChildren() for an internal directory:\n";
50    try {
51        // Open the existing PharData archive in read mode
52        $phar = new PharData($archiveName);
53
54        // Iterate through the top-level entries of the archive to find 'parent_dir'
55        $parentDirEntry = null;
56        foreach ($phar as $entry) {
57            // $entry is a PharFileInfo object representing an item in the archive
58            if ($entry->isDir() && $entry->getFilename() === $parentDir) {
59                $parentDirEntry = $entry;
60                break;
61            }
62        }
63
64        if ($parentDirEntry !== null) {
65            echo "Found directory '{$parentDirEntry->getPathname()}'. Listing its immediate children:\n";
66            // Call getChildren() on the PharFileInfo object representing 'parent_dir'.
67            // This returns a new PharData object (acting as an iterator) for the contents of 'parent_dir'.
68            $children = $parentDirEntry->getChildren();
69
70            if ($children !== null) {
71                // Iterate through the children to display their names and paths
72                foreach ($children as $child) {
73                    echo "- " . $child->getFilename() . " (path: " . $child->getPathname() . ")\n";
74                }
75            } else {
76                echo "Directory '{$parentDirEntry->getFilename()}' has no children.\n";
77            }
78        } else {
79            echo "Could not find '{$parentDir}' in the archive.\n";
80        }
81    } catch (PharException $e) {
82        echo "Error opening or reading PharData archive: " . $e->getMessage() . "\n";
83    } finally {
84        // --- Step 4: Clean up temporary files and archive ---
85        echo "\nCleaning up temporary files...\n";
86        @unlink($archiveName);
87        @unlink($fileA);
88        @unlink($fileB);
89        @rmdir($childDir);
90        @rmdir($parentDir); // Ensure parentDir is empty before removing
91        echo "Cleanup complete.\n";
92    }
93}
94
95// Execute the demonstration function
96demonstratePharDataGetChildren();

PHPのPharData::getChildren()メソッドは、Phar形式のアーカイブファイル（.tarや.zipなど）内に含まれる特定のディレクトリの直下の内容（子ファイルや子ディレクトリ）を一覧表示するために使用されます。

このサンプルコードでは、まず一時的にparent_dirというディレクトリとその内部にfile_a.txt、さらにchild_dirとその中にfile_b.txtという構造をファイルシステム上に作成します。次に、これらのファイルやディレクトリをnested_archive.tarという名前のPharDataアーカイブとしてパックします。アーカイブの作成後、これを読み込みモードで開き、アーカイブのトップレベルからparent_dirというエントリを検索します。

parent_dirを表すPharFileInfoオブジェクトが見つかったら、そのオブジェクトに対してgetChildren()メソッドを呼び出します。これにより、parent_dirの直下にあるすべてのエントリ（この例ではfile_a.txtとchild_dir）を取得し、それぞれのファイル名とパスを表示します。このメソッドは引数を必要としません。

戻り値としては、子要素を反復処理できる新しいPharDataオブジェクトが返されます。これにより、foreachループを使って個々の内容にアクセスできます。もし子要素が存在しない場合や、対象のエントリがディレクトリでないなどの理由で操作ができない場合はnullが返されます。処理の最後に、作成された一時ファイルとアーカイブはすべてクリーンアップされます。