phar 拡張モジュールは、 phar ストリームラッパーおよび Phar クラスを提供し、 PHP アーカイブ (phar) ファイルを操作することができます。 Phar クラスを使用すると、phar ファイルの作成や展開、 そしてその中身を順に処理することなどができます。
PHP アーカイブファイル (Phar) は複数のファイルをまとめたもので、 外部からその中のファイルを透過的に実行することができます。 Java の jar アーカイブファイルと似たものです。 phar アーカイブを使用すると、 PHP アプリケーションをひとつのファイルにまとめて配布できるようになります。 このファイルは、変更したり展開したりすることなくそのまま外部から実行できます。 phar アーカイブは、tar や zip のアーカイブと同様に、 ファイルを保存するために使用することもできます。 Phar は圧縮もサポートしています。 zlib 拡張モジュールが存在する場合には gzip を、そして bz2 拡張モジュールが存在する場合には bzip2 を使用します。 さらに、SPL 拡張モジュールが存在する場合には、 順次処理やその他の機能が使用可能となります。 md5 や sha1 による Phar の署名の検証は ネイティブでサポートされており、アーカイブの整合性を確かめることができます。
Phar アーカイブのネイティブな実装は PEAR パッケージ PHP_Archive であり、この拡張モジュールの実装はこれと非常によく似ています。 しかし Phar 拡張モジュールのほうが、より多くの機能をサポートしています。 PHP_Archive はより柔軟に Phar を作成することができます。また PHP_Archive_Manager クラスのような便利なデバッグツールも用意されています。 一方 Phar 拡張モジュールは、Phar の中身の順次処理や 配列形式でのアクセス、そして中身の変更などが シンプルなインターフェイスでできるようになります。 PHP_Archive は、Phar 拡張モジュールあるいは PHP_Archive のいずれかでシームレスに処理できる Phar アーカイブの作成をサポートしています。 一方、Phar 拡張モジュールは、 Phar 拡張モジュールで動作するアーカイブを作成するよう設計されています。 さらに Phar 拡張モジュールは、INI 設定 allow_url_include あるいは allow_url_fopen が無効になっていても動作します。一方 PHP_Archive で (Phar 拡張モジュールを使用せずに) 作成したアーカイブは動作しません。
Phar を使用するには PHP 5.2.0 以降が必要です。また、 Phar ファイルの中身に対して配列形式でアクセスしたり順に処理したりするには SPL 拡張モジュールが PHP に組み込まれている必要があります。 phar ストリームを使用するには、 これは不要です。
オプションとして、zlib 拡張モジュールおよび bzip2 拡張モジュールを有効にしておくと、 圧縮された phar をサポートすることができます。
Windows 用のバイナリは http://snaps.php.net/ にあります。インストールするには、php_phar.dll をダウンロードして、php.ini の extension_dir ディレクティブで指定されたフォルダに配置します。 その後、php.ini に extension=php_phar.dll を追加してこれを有効にし、ウェブサーバを再起動します。
extension_dir=c:/php5/exts/ extension=php_phar.dll |
Linux、BSD その他 *nix 系 の場合は、次の手順でコンパイルします。
次の手順か、
pecl install phar で、PECL/phar のインストーラを実行します。
phar.so を、ビルド時に表示されたディレクトリから php.ini の extension_dir ディレクトリにコピーします。
extension=phar.so を php.ini に追加します。
あるいはこちらの手順を実行します。
次のようにして、php.ini へのパスを設定します。
pecl config-set php_ini /path/to/php.ini
pecl install phar で、PECL/phar のインストーラを実行します。
ウェブサーバを再起動し、php.ini の設定を読み込ませます。
開発バージョン: 現在は、PECL/phar の 安定版 はまだありません。 アルファ版 の PECL/phar をインストールするには pecl install phar-alpha を実行します。
PEAR コマンドを使用しない PECL/phar のコンパイル: pecl install phar を使用すると、 PECL/phar を自動的にダウンロードし、インストールします。しかし、 tar ボールを PECL からダウンロードすることもできます。tar ボールを展開したルートディレクトリで phpize && ./configure --enable-phar && make を実行すると phar.so が出来上がります。 ビルドしたものを、上のようにしてインストールします。
この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 http://pecl.php.net/package/phar.
php.ini の設定により動作が変化します。
表 1. ファイルシステムおよびストリームの設定オプション
名前 | デフォルト | 変更の可否 | 変更履歴 |
---|---|---|---|
phar.readonly | "1" | PHP_INI_SYSTEM では有効化/無効化、PHP_INI_ALL では有効化のみ | バージョン 1.0.0 以降で使用可能 |
phar.require_hash | "0" | PHP_INI_SYSTEM では有効化/無効化、PHP_INI_ALL では有効化のみ | バージョン 1.0.0 以降で使用可能 |
以下に設定ディレクティブに関する 簡単な説明を示します。
phar.readonly
booleanこのオプションを使用すると、phar ストリームや Phar オブジェクトによる Phar アーカイブの作成や変更ができなくなります。 この設定は、実運用環境では常に有効にしておくべきです。 phar 拡張モジュールのこの機能は、 サーバ上に他のセキュリティ上の脆弱性があった場合に php ベースのウィルスを直接作成されてしまうことにつながります。
注意: この設定は、セキュリティ上の理由により php.ini でしか解除できません。 phar.readonly を php.ini で無効にした場合は、 ユーザがスクリプト内で phar.readonly の有効/無効を切りかえることができます。 phar.readonly を php.ini で有効にした場合は、 スクリプト内でこれを "再度有効にする" ことはできますが、無効にすることはできません。
phar.require_hash
booleanこのオプションを使用すると、署名つき (現在サポートしているのは MD5 および SHA1) の Phar アーカイブのみをオープンするようになります。 署名を含まない Phar アーカイブの処理はできません。
注意: この設定は、セキュリティ上の理由により php.ini でしか解除できません。 phar.require_hash を php.ini で無効にした場合は、 ユーザがスクリプト内で phar.require_hash の有効/無効を切りかえることができます。 phar.require_hash を php.ini で有効にした場合は、 スクリプト内でこれを "再度有効にする" ことはできますが、無効にすることはできません。
Phar 拡張モジュールで使用するリソースは phar ストリームで、これにより、phar 内のファイルへの透過的なアクセスが可能となります。 Phar ファイルのフォーマットについては ここ で説明されています。
リソース型は定義されていません。
Phar |
PharFileInfo |
PharException |
Phar アーカイブは Java の JAR アーカイブと似た概念のものですが、 PHP アプリケーションで使用する際に必要な機能をより柔軟に使用できるよう改良しています。 Phar アーカイブを使用すると、PHP アプリケーションやライブラリを ひとつのファイルにまとめて配布できるようになります。 Java における JAR アーカイブの実装とは異なり、 PHP の Phar アーカイブを処理したり実行したりするには外部のツールは不要です。 Phar アーカイブ形式のアプリケーションは、その他の PHP アプリケーションとまったく同様に扱えます。
php coolapplication.phar |
Phar アーカイブ形式のライブラリを使用する方法も、 その他の通常の PHP ライブラリとまったく同じです。
Phar アーカイブを非常に便利なものとしている機能が phar ストリームラッパーです。 詳細については こちら で説明します。このストリームラッパーを使用すると、 phar 内の個々のファイルに対して、 まるで通常のファイルシステム上にあるのと同じような感覚でアクセスできます。 phar ストリームラッパーは、 ファイルに対する読み書きや、ディレクトリに対する opendir() をすべてサポートしています。
<?php |
Phar 拡張モジュールで提供されているもうひとつの機能が Phar クラスです。 これにより、Phar アーカイブ内のファイルに対して まるでそれが連想配列であるかのようにアクセスできるようになります。 またその他の機能も用意されています。Phar クラスについての説明は こちら をご覧ください。
<?php |
Phar ストリームラッパーは、fopen() による読み込みや 書き込みそして追記、unlink()、stat()、 fstat()、fseek()、rename() そしてディレクトリに対する opendir() といった機能に完全に対応しています。 Phar ストリームラッパーはディレクトリの作成や削除には対応していません。 ファイルは単なるファイルとしてしか格納されず、 ディレクトリを抽象化した概念は存在しないからです。
Phar アーカイブ内の各ファイルの圧縮やファイル単位のメタデータの操作も、 ストリーム上で可能です。
<?php |
phar ストリームラッパーは、 リモートファイルを操作することはできません。つまり、INI 設定 allow_url_fopen および allow_url_include が無効になっている場合でも使用できます。
ストリーム操作だけで新しい phar アーカイブをゼロから作成することも可能ですが、 そんな場合は Phar クラスの組み込み機能を使用するほうが便利です。 ストリームラッパーが有用なのは、読み込み操作を行う場合です。
Phar クラスは Phar アーカイブの読み込みや操作をサポートしています。 また RecursiveDirectoryIterator クラスを継承しているため、順次処理も可能です。 ArrayAccess インターフェイスをサポートしているので、 Phar アーカイブ内のファイルに対して、 それがまるで連想配列であるかのようにアクセスすることができます。
注意すべき点は、Phar アーカイブを作成する際には Phar のコンストラクタに フルパスを渡さなければならないということです。 相対パスでは初期化に失敗します。
$p が、次のように作成した Phar オブジェクトであるとしましょう。
空の Phar アーカイブが /path/to/myphar.phar に作成されます。もし /path/to/myphar.phar が既に存在する場合は、それを再度オープンします。 リテラル myphar.phar は、エイリアスを表します。 これを用いると、URL で /path/to/myphar.phar を参照する際に次のようにできます。
<?php |
新しく作成した Phar オブジェクト $p に対して、次のような処理が可能となります。
$a = $p['file.php'] とすると、 phar://myphar.phar/file.php の中身を参照する PharFileInfo クラスが作成されます。
$p['file.php'] = $v とすると、 myphar.phar の中に新しいファイル (phar://myphar.phar/file.php) を作成するか、あるいは同名のファイルを上書きします。 $v には、文字列あるいはファイルポインタのいずれかを指定できます。 ファイルポインタを指定した場合は、その中身全体をもとにして新しいファイルを作成します。
isset($p['file.php']) とすると、phar://myphar.phar/file.php が myphar.phar の中に存在するかどうかがわかります。
unset($p['file.php']) とすると、 phar://myphar.phar/file.php を myphar.phar から削除します。
さらに、Phar 固有のメタデータにアクセスするためには Phar オブジェクトを使用することが唯一の方法となります。そのためには Phar->getMetaData() を使用します。また、Phar アーカイブの PHP ローダスタブを設定したり取得したりするための唯一の方法が Phar->getStub() および Phar->setStub() です。 また、Phar アーカイブ全体の圧縮を行うには Phar クラスが必要となります。
Phar オブジェクトの全機能の一覧については、以下で説明します。
PharFileInfo クラスは SplFileInfo クラスを継承しており、Phar 内のファイルについての Phar 固有の情報 (圧縮情報やメタデータなど) を扱うためのメソッドが追加されています。
Phar ファイルは、三つあるいは四つの部分から構成されています。
スタブ
内容を説明するマニフェスト
ファイルの内容
[オプション] Phar の整合性を検証するためのシグネチャ
Phar のスタブは、単純な PHP ファイルです。必要最小限のスタブは、次のようになります。
<?php __HALT_COMPILER();
|
スタブには、少なくとも __HALT_COMPILER(); トークンが必要です。 典型的なスタブは、次のように読み込み機能を含んでいます。
<?php |
Phar スタブの内容には特に制限はありません。唯一の制約は、最後が __HALT_COMPILER(); でなければならないということです。 PHP の終了タグ ?> は含めても含めなくてもかまいません。 しかし、; と終了タグ ?> の間にはひとつ以上の空白を含めてはいけません。 もしそうしてしまうと、phar 拡張モジュールは その Phar アーカイブのマニフェストを処理できなくなります。
Phar マニフェストは高度に最適化された書式で、 ファイル単位で圧縮やパーミッションの情報を指定することができ、 さらにファイルのユーザやグループなど、独自に定義したメタデータも含めることができます。 1 バイトをこえる大きさの値はリトルエンディアン形式のバイト順で保存されます。 ただし API バージョンだけは例外です。これは 3 ニブルのデータですが、 歴史的な理由によりビッグエンディアン形式のバイト順で保存されます。
未使用のフラグはすべて将来の使用に備えて予約されています。 したがって、独自の情報を保存するためにそれを使用してはいけません。 特定のファイルについて独自の情報を保存するには、 ファイル単位のメタデータ機能を使用します。
Phar アーカイブマニフェストの基本的なファイルフォーマットは、次のようになります。
表 2. グローバル Phar マニフェスト書式
バイト数 | 説明 |
---|---|
4 バイト | マニフェスト全体のバイト長 (最大 1 MB)。 |
4 バイト | Phar 内のファイル数。 |
2 バイト | Phar マニフェストの API バージョン (現在は 1.0.0)。 |
4 バイト | グローバルな Phar ビットマップフラグ。 |
4 バイト | Phar のエイリアスの長さ。 |
?? | Phar のエイリアス (先ほどの長さに基づきます)。 |
4 バイト | Phar のメタデータの長さ (存在しない場合は 0)。 |
?? | シリアライズ化された Phar メタデータ。serialize() 形式で格納される。 |
最低でも 24 * エントリ数ぶんのバイト | 各ファイルのエントリ |
マニフェスト内の各ファイルについて、次のような情報が含まれます。
表 4. Phar マニフェストのファイルエントリ
バイト数 | 説明 |
---|---|
4 バイト | ファイル名の長さを表すバイト数。 |
?? | ファイル名 (先ほど指定した長さになります)。 |
4 バイト | 圧縮前のファイルサイズを表すバイト数。 |
4 バイト | ファイルの Unix タイムスタンプ。 |
4 バイト | 圧縮後のファイルサイズを表すバイト数。 |
4 バイト | 圧縮前のファイルの CRC32 チェックサム。 |
4 バイト | ファイル固有のビットマップフラグ。 |
4 バイト | シリアライズされたファイルのメタデータの長さ (存在しない場合は 0)。 |
?? | シリアライズされたファイルのメタデータ。serialize() の形式で格納される。 |
ファイル固有のビットマップ値として認識される値は次のとおりです。
表 5. 認識されるビットマップ値
値 | 説明 |
---|---|
0x000001FF | これらのビットは、ファイルの特定のパーミッションを定義するために予約されています。 このパーミッションは fstat() で用いられ、 ファイルを展開する際に特定のパーミッションを指定することができます。 |
0x00001000 | 設定されている場合、このファイルは zlib で圧縮されています。 |
0x00002000 | 設定されている場合、このファイルは bzip で圧縮されています。 |
シグネチャを含む Phar は、常にシグネチャを保持しています。 シグネチャの場所は、 ローダ、マニフェスト、実際のファイルの内容に続く Phar アーカイブの最後の部分です。 現在サポートしているシグネチャのフォーマットは MD5 および SHA1 の二種類です。