php/archived-doc-ja
1
0
Fork 0
mirror of https://github.com/php/doc-ja.git synced 2026-03-23 22:52:11 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
master
archived-doc-ja/reference/phar/fileformat.xml

532 lines
20 KiB
XML
Raw Permalink Blame History

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: f9c4a68ef4f89e51e6d9b905ad3ddb6492386dd3 Maintainer: takagi Status: ready -->
<!-- Credits: shimooka,mumumu -->
<chapter xml:id="phar.fileformat" xmlns="http://docbook.org/ns/docbook">
<title>phar って、tar や zip とは何が違うの?</title>
<section xml:id="phar.fileformat.ingredients" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Phar アーカイブの原料のうち、ファイル形式に依存しないもの</title>
<para>
すべての Phar アーカイブは、三つあるいは四つの部分から構成されています。
<orderedlist>
<listitem>
<para>スタブ</para>
</listitem>
<listitem>
<para>内容を説明するマニフェスト</para>
</listitem>
<listitem>
<para>ファイルの内容</para>
</listitem>
<listitem>
<para>[オプション] Phar の整合性を検証するためのシグネチャ (phar 形式の場合のみ)</para>
</listitem>
</orderedlist>
</para>
</section>
<section xml:id="phar.fileformat.stub" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Phar ファイルのスタブ</title>
<para>
Phar のスタブは、単純な PHP ファイルです。必要最小限のスタブは、次のようになります。
</para>
<para>
<programlisting role="php">
<![CDATA[<?php __HALT_COMPILER();]]>
</programlisting>
</para>
<para>
スタブには、少なくとも <literal>__HALT_COMPILER();</literal> トークンが必要です。
典型的なスタブは、次のように読み込み機能を含んでいます。
</para>
<para>
<programlisting role="php">
<![CDATA[
<?php
Phar::mapPhar();
include 'phar://myphar.phar/index.php';
__HALT_COMPILER();
]]>
</programlisting>
</para>
<para>
Phar スタブの内容には特に制限はありません。唯一の制約は、最後が
<literal>__HALT_COMPILER();</literal> でなければならないということです。
PHP の終了タグ <literal><![CDATA[?>]]></literal> は含めても含めなくてもかまいません。
しかし、<literal>;</literal> と終了タグ
<literal><![CDATA[?>]]></literal> の間にはひとつ以上の空白を含めてはいけません。
もしそうしてしまうと、phar 拡張モジュールは
その Phar アーカイブのマニフェストを処理できなくなります。
</para>
<para>
tar 形式あるいは zip 形式の phar アーカイブでは、スタブは
<literal>.phar/stub.php</literal> というファイルに保存されます。
phar 形式の phar アーカイブのデフォルトのスタブには
約 7k のコードが含まれており、このコードが phar の展開と実行を行います。
詳細は <function>Phar::createDefaultStub</function> を参照ください。
</para>
<para>
tar 形式あるいは zip 形式の phar アーカイブにおける
phar エイリアスの保存先は
<literal>.phar/alias.txt</literal> で、これはプレーンテキスト形式となります。
</para>
</section>
<section xml:id="phar.fileformat.comparison" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Phar 形式と Tar 形式、Zip 形式の徹底比較</title>
<para>
phar 拡張モジュールがサポートする 3 つのファイル形式って、何がどう違うのでしょう?
その答えを次の表にまとめました。
<table>
<title>機能マトリックス: Phar vs. Tar vs. Zip</title>
<tgroup cols="4">
<thead>
<row>
<entry>機能</entry>
<entry>Phar</entry>
<entry>Tar</entry>
<entry>Zip</entry>
</row>
</thead>
<tbody>
<row>
<entry>一般的なファイル形式</entry>
<entry>No</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Phar 拡張モジュールなしでの実行
<link linkend="phar.fileformat.phartip">[1]</link>
</entry>
<entry>Yes</entry>
<entry>No</entry>
<entry>No</entry>
</row>
<row>
<entry>ファイル単位での圧縮</entry>
<entry>Yes</entry>
<entry>No</entry>
<entry>Yes</entry>
</row>
<row>
<entry>アーカイブ全体の圧縮</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>アーカイブ全体のシグネチャによる検証</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>ウェブアプリケーションへの対応</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>ファイルごとのメタデータ</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>アーカイブ単位のメタデータ</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>アーカイブの作成/変更
<link linkend="phar.fileformat.phartip2">[2]</link>
</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>すべてのストリームラッパー関数への対応</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>phar.readonly=1 の場合でも作成/変更が可能
<link linkend="phar.fileformat.phartip3">[3]</link>
</entry>
<entry>No</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para xml:id="phar.fileformat.phartip">
<tip>
<para>
[1] Phar 拡張モジュールが使用できない環境で Phar
アーカイブの中身に PHP からアクセスする場合は、その
<literal>スタブ</literal> を使用します。ここに
phar アーカイブの中身を展開するコードが含まれています。
phar 拡張モジュールが見つからない場合は、
<function>Phar::createDefaultStub</function> で作成したスタブが
phar アーカイブを展開し、テンポラリディレクトリ内でそれを実行します。
</para>
</tip>
</para>
<para xml:id="phar.fileformat.phartip2">
<tip>
<para>
[2] 書き込みアクセスを行うには、php.ini あるいはコマンドラインで
<literal>phar.readonly</literal> を無効にする必要があります。
</para>
</tip>
</para>
<para xml:id="phar.fileformat.phartip3">
<tip>
<para>
[3] tar および zip 形式のアーカイブでファイル名に <literal>.phar</literal>
がつかない、かつ実行スタブ <literal>.phar/stub.php</literal>
を含まないファイルは phar.readonly=1 でも作成できます。
</para>
</tip>
</para>
</section>
<section xml:id="phar.fileformat.tar" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Tar 形式の phar アーカイブ</title>
<para>
tar 形式のアーカイブは、より近代的な USTAR フォーマットを使用しています。
tar 形式のファイルヘッダは、zip 形式よりも効率的にアクセスできるよう設計されています。
また、phar ファイルフォーマットともほぼ同じくらいに効率的です。
phar アーカイブ内のファイル名は、フルパスで 255 バイトまでという制限があります。
tar 形式の phar アーカイブでは、アーカイブ内のファイルの数に制限はありません。
このアーカイブは gzip や bzip2 で圧縮することができ、
そのまま Phar 拡張モジュールで実行できます。
</para>
<para>
pax 中間フォーマット経由で、tarボールを読み込む機能も限定的ながらサポートされていますが、
全ての認識される pax ヘッダ
(今のところ、型フラグ <literal>x</literal> と <literal>g</literal>) は静かに無視されます。
GNU tar アーカイブも限定的ながらサポートされていますが、
今のところ、<literal>././@LongLink</literal> を解決するのみにとどまっています。
</para>
<para>
アーカイブ全体を圧縮するには <function>Phar::compress</function>
を使用します。
アーカイブ全体の圧縮を解くには <function>Phar::decompress</function>
を使用します。
</para>
</section>
<section xml:id="phar.fileformat.zip" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Zip 形式の phar アーカイブ</title>
<para>
zip 形式のアーカイブは、zip ファイル形式に組み込まれているいくつかの機能に対応しています。
ファイルごとのメタデータやアーカイブ全体のメタデータを、
文字列にシリアル化して
zip ファイルのコメントや zip アーカイブのコメントとして格納することができます。
また、既存の zip コメントも文字列として読み込むことができます。
zlib 圧縮ではファイル単位の DEFLATE 圧縮の読み書き、
そして bzip2 圧縮ではファイル単位の圧縮の読み込みに対応しています。
zip 形式の phar アーカイブでは、アーカイブ内のファイルの数に制限はありません。
空のディレクトリを zip アーカイブに保存する際には、最後にスラッシュをつけた
<literal>my/directory/</literal> のような形式のファイルとなります。
</para>
</section>
<section xml:id="phar.fileformat.phar" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Phar ファイルフォーマット</title>
<para>
phar ファイル形式は スタブ/マニフェスト/コンテンツ/シグネチャ
で構成されており、phar アーカイブ内に何が含まれているのかについての重要な情報は
<literal>マニフェスト</literal> に格納されます。
</para>
<para>
Phar マニフェストは高度に最適化された書式で、
ファイル単位で圧縮やパーミッションの情報を指定することができ、
さらにファイルのユーザーやグループなど、独自に定義したメタデータも含めることができます。
1 バイトをこえる大きさの値はリトルエンディアン形式のバイト順で保存されます。
ただし API バージョンだけは例外です。これは 3 ニブルのデータですが、
歴史的な理由によりビッグエンディアン形式のバイト順で保存されます。
</para>
<para>
未使用のフラグはすべて将来の使用に備えて予約されています。
したがって、独自の情報を保存するためにそれを使用してはいけません。
特定のファイルについて独自の情報を保存するには、
ファイル単位のメタデータ機能を使用します。
</para>
<para>
Phar アーカイブマニフェストの基本的なファイルフォーマットは、次のようになります。
</para>
<para>
<table>
<title>グローバル Phar マニフェスト書式</title>
<tgroup cols="2">
<thead>
<row>
<entry>バイト数</entry>
<entry>説明</entry>
</row>
</thead>
<tbody>
<row>
<entry>4 バイト</entry>
<entry>マニフェスト全体のバイト長 (最大 1 MB)。</entry>
</row>
<row>
<entry>4 バイト</entry>
<entry>Phar 内のファイル数。</entry>
</row>
<row>
<entry>2 バイト</entry>
<entry>Phar マニフェストの API バージョン (現在は 1.0.0)。</entry>
</row>
<row>
<entry>4 バイト</entry>
<entry>グローバルな Phar ビットマップフラグ。</entry>
</row>
<row>
<entry>4 バイト</entry>
<entry>Phar のエイリアスの長さ。</entry>
</row>
<row>
<entry>??</entry>
<entry>Phar のエイリアス (先ほどの長さに基づきます)。</entry>
</row>
<row>
<entry>4 バイト</entry>
<entry>Phar のメタデータの長さ (存在しない場合は <literal>0</literal>)。</entry>
</row>
<row>
<entry>??</entry>
<entry>シリアライズされた Phar メタデータ。<function>serialize</function> 形式で格納される。</entry>
</row>
<row>
<entry>最低でも 24 * エントリ数ぶんのバイト</entry>
<entry>各ファイルのエントリ</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
<section xml:id="phar.fileformat.flags" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>グローバルな Phar ビットマップフラグ</title>
<para>
これが、Phar 拡張モジュールが現在 Phar フラットビットマップとして認識するフラグです。
</para>
<para>
<table>
<title>認識するビットマップ値</title>
<tgroup cols="2">
<thead>
<row>
<entry>値</entry>
<entry>説明</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>0x00010000</literal></entry>
<entry>設定されている場合、この Phar には検証用シグネチャが含まれます。</entry>
</row>
<row>
<entry><literal>0x00001000</literal></entry>
<entry>
設定されている場合、この Phar には
zlib DEFLATE 圧縮されたファイルが少なくともひとつ含まれます。
</entry>
</row>
<row>
<entry><literal>0x00002000</literal></entry>
<entry>
設定されている場合、この Phar には
bzip2 圧縮されたファイルが少なくともひとつ含まれます。
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
<section xml:id="phar.fileformat.manifestfile" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Phar マニフェストのファイルエントリの定義</title>
<para>
マニフェスト内の各ファイルについて、次のような情報が含まれます。
</para>
<para>
<table>
<title>Phar マニフェストのファイルエントリ</title>
<tgroup cols="2">
<thead>
<row>
<entry>バイト数</entry>
<entry>説明</entry>
</row>
</thead>
<tbody>
<row>
<entry>4 バイト</entry>
<entry>ファイル名の長さを表すバイト数。</entry>
</row>
<row>
<entry>??</entry>
<entry>ファイル名 (先ほど指定した長さになります)。</entry>
</row>
<row>
<entry>4 バイト</entry>
<entry>圧縮前のファイルサイズを表すバイト数。</entry>
</row>
<row>
<entry>4 バイト</entry>
<entry>ファイルの Unix タイムスタンプ。</entry>
</row>
<row>
<entry>4 バイト</entry>
<entry>圧縮後のファイルサイズを表すバイト数。</entry>
</row>
<row>
<entry>4 バイト</entry>
<entry>圧縮前のファイルの CRC32 チェックサム。</entry>
</row>
<row>
<entry>4 バイト</entry>
<entry>ファイル固有のビットマップフラグ。</entry>
</row>
<row>
<entry>4 バイト</entry>
<entry>シリアライズされたファイルのメタデータの長さ (存在しない場合は <literal>0</literal>)。</entry>
</row>
<row>
<entry>??</entry>
<entry>シリアライズされたファイルのメタデータ。<function>serialize</function> の形式で格納される。</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
API バージョン 1.1.1 では、空のディレクトリの最後にスラッシュをつけて
<literal>my/directory/</literal> のような形式で保存されることに注意しましょう。
</para>
<para>
ファイル固有のビットマップ値として認識される値は次のとおりです。
</para>
<para>
<table>
<title>認識されるビットマップ値</title>
<tgroup cols="2">
<thead>
<row>
<entry>値</entry>
<entry>説明</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>0x000001FF</literal></entry>
<entry>
これらのビットは、ファイルの特定のパーミッションを定義するために予約されています。
このパーミッションは <function>fstat</function> で用いられ、
ファイルを展開する際に特定のパーミッションを指定することができます。
</entry>
</row>
<row>
<entry><literal>0x00001000</literal></entry>
<entry>
設定されている場合、このファイルは
zlib DEFLATE 圧縮されています。
</entry>
</row>
<row>
<entry><literal>0x00002000</literal></entry>
<entry>
設定されている場合、このファイルは
bzip2 圧縮されています。
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
<section xml:id="phar.fileformat.signature" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Phar のシグネチャの書式</title>
<para>
シグネチャを含む Phar は、常にシグネチャを保持しています。
シグネチャの場所は、
ローダ、マニフェスト、実際のファイルの内容に続く
Phar アーカイブの最後の部分です。
現在サポートしているシグネチャのフォーマットは
MD5, SHA1, SHA256, SHA512, OPENSSL です。
</para>
<para>
<table>
<title>シグネチャのフォーマット</title>
<tgroup cols="2">
<thead>
<row>
<entry>バイト長</entry>
<entry>説明</entry>
</row>
</thead>
<tbody>
<row>
<entry>可変長</entry>
<entry>
実際のシグネチャ。SHA1 の場合は 20 バイト、
MD5 の場合は 16 バイト、
SHA256 の場合は 32 バイト、
そして SHA512 の場合は 64 バイトとなります。
OPENSSL の場合は、秘密鍵の長さに応じて変化します。
</entry>
</row>
<row>
<entry>4 バイト</entry>
<entry>
シグネチャのフラグ。<literal>0x0001</literal> は
MD5 シグネチャ、そして <literal>0x0002</literal> は
SHA1 シグネチャ、
<literal>0x0003</literal> は SHA256 シグネチャ、
<literal>0x0004</literal> は SHA512 シグネチャを表します。
SHA256 および SHA512 は、API バージョン 1.1.0 以降で利用可能です。
<literal>0x0010</literal> は OPENSSL シグネチャを表します。
これは API バージョン 1.1.1 以降、
かつ OpenSSL と共にビルドされている場合にのみ利用可能です。
</entry>
</row>
<row>
<entry>4 バイト</entry>
<entry>
<literal>GBMB</literal> という固定値で、
シグネチャが存在することを表します。
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
Reference in New Issue View Git Blame Copy Permalink