cvs: peardoc /ja/package/fileformats/file-archive archmod.xml cache.xml examples-gallery.xml examples.xml predicates.xml readers.xml writers.xml

takagi Thu Feb 28 07:26:46 2008 UTC Added files: /peardoc/ja/package/fileformats/file-archive writers.xml readers.xml predicates.xml examples.xml examples-gallery.xml cache.xml archmod.xml Log: added Japanese translation.

http://cvs.php.net/viewvc.cgi/peardoc/ja/package/fileformats/file-archive/writers.xml?view=markup&rev=1.1 Index: peardoc/ja/package/fileformats/file-archive/writers.xml +++ peardoc/ja/package/fileformats/file-archive/writers.xml <?xml version="1.0" encoding="utf-8" ?> <!-- $Revision: 1.1 $ --> <!-- EN-Revision: 1.1 Maintainer: takagi Status: ready --> <refentry id="package.fileformats.file-archive.writers"> <refnamediv> <refname>ライター</refname> <refpurpose>アーカイブの保存</refpurpose> </refnamediv> <refsect1 id="package.fileformats.file-archive.writers.intro"> <title>導入</title> <para> ライターは、データを扱うオブジェクトです。 データを変換する (アーカイブライターの場合) ライターもあれば、ディスクに保存する (ファイルライターの場合) ものやメモリに保存する (メモリライターの場合) もあります。これらはみな同じインターフェイスを実装しています。 </para> <para> リーダーからのデータをライターに移すには <command>File_Archive::extract</command> 関数を使用します。 </para> <para> すべてのライターは <classname>File_Archive</classname> ファクトリで作成されます。 より正確に言うと、<command>File_Archive::to*</command> 関数を使用します。 </para> </refsect1> <refsect1 id="package.fileformats.file-archive.writers.writearchives"> <title>アーカイブの書き込み</title> <para> アーカイブを生成するライターは、 <function>toArchive</function> 関数で作成します。 </para> <funcsynopsis> <funcprototype> <funcdef> <function>toArchive</function> </funcdef> <paramdef> &type.string; <parameter>$filename</parameter> </paramdef> <paramdef> <parameter>&amp;$innerWriter</parameter> </paramdef> <paramdef> <parameter><optional>$type = null</optional></parameter> </paramdef> <paramdef> <parameter><optional>$stat = array()</optional></parameter> </paramdef> <paramdef> <parameter><optional>$autoClose = true</optional></parameter> </paramdef> </funcprototype> </funcsynopsis> <itemizedlist> <listitem> <para> <varname>$filename</varname> は、生成されるアーカイブの名前です。 </para> </listitem> <listitem> <para> <varname>$innerWriter</varname> は、アーカイブファイルを書き込む別のライターです。 </para> </listitem> <listitem> <para> <varname>$type</varname> は <literal>Tar</literal> か <literal>Gzip</literal>、<literal>Zip</literal> のいずれかで、 圧縮方式を表します。指定しなかった場合は、 ファイル名の拡張子から判断します。 </para> </listitem> <listitem> <para> <varname>$stat</varname> はオプションの配列で、 アーカイブに関する状態を表します (使用できるインデックスについては PHP の stat 関数を参照ください)。 </para> </listitem> <listitem> <para> <varname>$autoClose</varname> は、 データを送信した後に内部のライターをクローズするかどうかを表します。 書き込んだ後に何らかのデータを追記したいのなら、 ライターをクローズしないほうが便利でしょう。 一般には、ライターをオープンし続ける必要はありません。 したがって、デフォルト値のままにしておくことになります。 </para> </listitem> </itemizedlist> <example> <title>アーカイブライターの作成</title> <programlisting role="php"><![CDATA[ <?php require_once "File/Archive.php"; /* tar ファイルに書き込むライター */ File_Archive::toArchive("archive.tar", $innerWriter); /* tar.gz ファイルに書き込むライター */ File_Archive::toArchive("archive.tgz", $innerWriter); /* zip ファイルに書き込むライター */ File_Archive::toArchive("archive.zip", $innerWriter); ?>]]></programlisting> </example> </refsect1> <refsect1 id="package.fileformats.file-archive.writers.writefiles"> <title>ファイルへの書き込み</title> <para> ライターは、ファイルの内容を物理ファイルに書き込むことができます。 そのようなライターを作成するには <command>File_Archive::toFiles();</command> をコールします。ディレクトリが存在しない場合は自動的に作成します。 </para> <example> <title>ファイルライターの使用法</title> <programlisting role="php"><![CDATA[ <?php require_once "File/Archive.php"; /* ディレクトリ全体を別の場所にコピーします */ File_Archive::extract( File_Archive::read('Path/to/dir', 'new/directory'); File_Archive::toFiles() ); /* アーカイブの形式を tgz から zip に変換します */ File_Archive::extract( File_Archive::read('archive.tgz/'), File_Archive::toArchive( 'archive.zip', File_Archive::toFiles() ) ); ?>]]></programlisting> </example> </refsect1> <refsect1 id="package.fileformats.file-archive.writers.sendmails"> <title>メールの送信</title> <para> メールの添付ファイルとして送信するには、 <command>File_Archive::toMail</command> 関数でメールライターを作成します。 </para> <funcsynopsis> <funcprototype> <funcdef> <function>toMail</function> </funcdef> <paramdef> &type.array; <parameter>$to</parameter> </paramdef> <paramdef> &type.array; <parameter>$headers</parameter> </paramdef> <paramdef> &type.string; <parameter>$message</parameter> </paramdef> <paramdef> <parameter><optional>&amp;$mail = null</optional></parameter> </paramdef> </funcprototype> </funcsynopsis> <para> この関数は PEAR の <classname>Mail</classname> および <classname>Mail_Mime</classname> ライブラリを使用しており、 パラメータはこれらのクラスと同じです。 </para> <itemizedlist> <listitem> <para> <varname>$to</varname> は、配列あるいはカンマ区切りの文字列で受信者を指定します。 </para> </listitem> <listitem> <para> <varname>$headers</varname> は <classname>Mail_Mime</classname> と <varname>$mail</varname> に送られる、ヘッダの連想配列です。ヘッダの名前が連想配列のキー、 ヘッダの値が連想配列の値となります。 </para> </listitem> <listitem> <para> <varname>$message</varname> はメールの本文にあたるテキストです。 HTML 形式にするには、ライターの <function>setHTMLBody</function> および <function>addHTMLImage</function> を使用します。これらの関数のシグネチャは <classname>Mail_Mime</classname> のものと同じです。 </para> </listitem> <listitem> <para> <varname>$mail</varname> はメールを送る方法です。 <function>Mail::factory</function> 関数で作成したオブジェクトを使用します。 <literal>null</literal> の場合は <command>Mail::factory('mail')</command> を使用します (そして、PHP の mail 関数を用いてメールを送信します)。 </para> </listitem> </itemizedlist> <example> <title></title> <programlisting role="php"><![CDATA[ <?php require_once "File/Archive.php"; /* カレントディレクトリ (再帰なし) のファイルを添付ファイルとして送信します */ File_Archive::extract( File_Archive::read('Path/to/dir', '', 0, 0), File_Archive::toMail( $to, // 受信者 array( 'Subject' => 'Path/to/dir directory', 'From' => 'address@of.expeditor' ), '見つかったファイルをすべて添付しました' // 本文 ) ); ?>]]></programlisting> </example> </refsect1> <refsect1 id="package.fileformats.file-archive.writers.stdout"> <title>ユーザへのファイルの送信</title> <para> ファイルをリモートユーザに送信する (つまり、データを標準出力に送る) には、特別なライターが必要です。これは、関数 <function>File_Archive::toOutput</function> をコールして作成します。 </para> <para> このライターは、ファイルをダウンロードさせるようなヘッダを自動的に送信します。 </para> <para> ヘッダを送信させたくない場合は <command>File_Archive::toOutput(false)</command> とコールします。 </para> </refsect1> <refsect1 id="package.fileformats.file-archive.writers.multiwriters"> <title>マルチライター</title> <para> マルチライターを使用すれば、 ふたつ以上の場所にデータを平行に書き出すことができます。 </para> <para> 典型的な使用法は、ユーザ向けにデータを送信すると同時にファイルにも書き出すといったものです。 </para> <para> また、複数の形式のアーカイブを作成する際にも使用できます。 </para> <para> マルチライターを作成するには <command>File_Archive::toMulti($dest1, $dest2)</command> を使用します。 </para> <example> <title>マルチライター</title> <programlisting role="php"><![CDATA[ <?php // ディレクトリの内容をユーザとファイルに送信します File_Archive::extract( File_Archive::read('directory'), File_Archive::toArchive( 'multi.zip', File_Archive::toMulti( File_Archive::toOutput(), File_Archive::toFiles() ) ) ); ?> ]]></programlisting> </example> </refsect1> <refsect1 id="package.fileformats.file-archive.writers.writing"> <title>ライターへの書き込み</title> <para> リーダーを使わずに、データを直接ライターに書き込むこともできます。 そのためには、各ライターが実装している以下のインターフェイスを使用します。 </para> <itemizedlist> <listitem> <para><command>function newFile($URL, $stat)</command></para> <para> ライター内に新しいファイルを作成します。 </para> <para> <varname>$URL</varname> はファイルの名前、 <varname>$stat</varname> はデータについての情報の配列 (詳細は PHP の <function>stat</function> 関数を参照ください) です。 </para> <para> 情報の配列にはすべての情報を含める必要はありません。 必須なのは、インデックス 7 (データのサイズ) だけです。 </para> </listitem> <listitem> <para><command>function writeData($data)</command></para> <para> 指定したデータをライターに追記します。 事前に <function>newFile</function> をコールしておく必要があります。 </para> </listitem> <listitem> <para><command>function close()</command></para> <para> ライターをクローズし、データをフラッシュし、 そしてフッターを書き出します。 この関数は、ファイルの終端に達する前にコールしなければなりません。 そうしないとライターがデータを取りこぼしてしまうかもしれません。 </para> </listitem> </itemizedlist> <example> <title>zip ファイルの動的な作成</title> <programlisting role="php"><![CDATA[ <?php require_once "File/Archive.php"; $dest = File_Archive::toArchive("foo.zip", File_Archive::toFiles()); $dest->newFile("even.txt"); for($i=0; $i<100; $i++) $dest->writeData((2*$i)."\n"); $dest->newFile("odd.txt"); for($i=0; $i<100; $i++) $dest->writeData((2*$i+1)."\n"); $dest->close(); ?>]]></programlisting> </example> <note> <para> <function>newFile</function> 関数で情報の配列を指定しない場合は、 ファイルの終端に達するまでアーカイブの大半のデータをバッファリングする必要が生じます (通常は、ファイルのサイズがわからなければヘッダを書き込めないからです)。 </para> <para> 巨大なファイルを扱う際には、これはメモリの問題を引き起こす可能性があります。 </para> </note> </refsect1> <refsect1 id="package.fileformats.file-archive.writers.functionsusing"> <title>ライターを使用する関数</title> <para> 引数としてライターを受け取る <classname>File_Archive</classname> のすべての関数は、文字列および配列の両方の形式を受け付けます。 文字列は、<function>File_Archive::appender</function> 関数を用いて自動的にライターとして解釈されます。 配列はマルチライターと解釈されます。 </para> <para> ライターは参照渡しとなるので、生の文字列や配列ではなく変数を渡す必要があります。 </para> <para> したがって、先ほどの例は次のように書き換えることもできます。 </para> <example> <title>マルチライター</title> <programlisting role="php"><![CDATA[ <?php // ディレクトリの内容をユーザとファイルに送信します File_Archive::extract( $src = 'directory', File_Archive::toArchive( 'multi.zip', array( File_Archive::toOutput(), File_Archive::toFiles() ) ) ); ?>]]></programlisting> </example> </refsect1> </refentry> http://cvs.php.net/viewvc.cgi/peardoc/ja/package/fileformats/file-archive/readers.xml?view=markup&rev=1.1 Index: peardoc/ja/package/fileformats/file-archive/readers.xml +++ peardoc/ja/package/fileformats/file-archive/readers.xml <?xml version="1.0" encoding="utf-8" ?> <!-- $Revision: 1.1 $ --> <!-- EN-Revision: 1.1 Maintainer: takagi Status: ready --> <refentry id="package.fileformats.file-archive.readers"> <refnamediv> <refname>リーダー</refname> <refpurpose>アーカイブへのファイルの取得</refpurpose> </refnamediv> <refsect1 id="package.fileformats.file-archive.readers.intro"> <title>導入</title> <para> リーダーは、ファイルやディレクトリの一覧を表すオブジェクトです。 これらのファイルは動的に作成することもできますし、 既存の物理ファイルを使用することもできます。 たとえば、ディレクトリ用のリーダークラスや <classname>File_Archive</classname> がサポートする各種アーカイブ形式を処理するためのリーダーがあります。 そして、それぞれが同じインターフェイスを持っています。 </para> <para> リーダーを作成するには <classname>File_Archive</classname> ファクトリを使用します。 重要な関数は <function>read</function> 関数です。 </para> <funcsynopsis> <funcprototype> <funcdef> <function>read</function> </funcdef> <paramdef> &type.string; <parameter>$url</parameter> </paramdef> <paramdef> &type.string; <parameter><optional>$symbolic = null</optional></parameter> </paramdef> <paramdef> &type.int; <parameter><optional>$uncompression = 0</optional></parameter> </paramdef> <paramdef> &type.int; <parameter><optional>$directoryDepth = -0</optional></parameter> </paramdef> </funcprototype> </funcsynopsis> <para> この関数の URL が、読み込みたい内容を表します。 </para> <example> <title>Generation of sources</title> <programlisting role="php"><![CDATA[ <?php require_once "File/Archive.php"; /* ディレクトリを読み込むにはディレクトリ名を指定します。 デフォルトでは、そのディレクトリだけでなくすべてのサブディレクトリも パースします (これを変更するには $directoryDepth を参照ください) */ $source = File_Archive::read("Path/to/dir"); /* 単一のファイルから読み込むには そのファイルの名前を指定します。 */ $source = File_Archive::read("Path/to/dir/file.txt"); /* アーカイブの後にスラッシュを続けると、ディレクトリとみなされます。 この例は、アーカイブ Path/to/dir/archive.tar の内部のディレクトリ inner/dir の中身を読み込みます。これは、archive.tar の inner ディレクトリにある すべての .txt ファイルを読み込みます。 */ $source = File_Archive::read("Path/to/dir/archive.tar/inner/*.txt"); /* アーカイブの内容を伸長したい (すｂての中身を読み込みたい) 場合はこのようにします。 注意: 最後の / を忘れると、アーカイブそのものが単一のファイルとして扱われてしまいます */ $source = File_Archive::read("Path/to/dir/archive.tar/"); ?> ]]></programlisting> </example> <para> <literal>symbolic</literal> 属性は、 読み込んだファイルを後でどのように表示するかを表します。 <varname>$URL</varname> がディレクトリの場合は、<varname>$URL</varname> が <varname>$symbolic</varname> (<varname>$symbolic</varname> が <literal>null</literal> の場合は <literal>''</literal>) で置き換えられます。 したがって、最初の例では、カレントディレクトリが <literal>'Path/to/dir'</literal> であるかのようにファイルが表示されます。 デフォルトでは <varname>$symbolic</varname> は空なので、 <literal>Path/to/dir</literal> がファイル名から取り除かれます。 <literal>Path/to/dir</literal> を <varname>$symbolic</varname> に設定すれば、フルパス <literal>Path/to/dir</literal> を保持できます。 </para> <para> <varname>$URL</varname> がファイルの場合は、ファイル名のみが保持されて <varname>$symbolic</varname> がそこに付け加えられます。 つまり、2 番目の例では、元ファイル名は <literal>file.txt</literal> となります。 シンボリック名 <literal>foo</literal> を指定すると、 これは <literal>foo/file.txt</literal> となります。 </para> <para> <varname>$uncompression</varname> パラメータは、 ツリーをファイルにパースする際に何個のファイルを伸長するかを表します。 デフォルトでは伸長は行いません。したがって、 <command>File_Archive::read('archive.tar/inner/dir', 'inner/dir')</command> を実行した際に <filename>archive.tar</filename> の中にもし <filename>archive.tar/inner/dir/file.tgz</filename> というファイルがあれば、 この第二のアーカイブはディレクトリではなくファイルとして扱われます。 <varname>$uncompression</varname> が <literal>0</literal> であるため、このアーカイブは伸長されないのです。 <varname>$uncompression</varname> を <literal>1</literal> にすると、 <filename>file.tgz</filename> はディレクトリとして扱われます。 しかし、このアーカイブの中のファイルは伸長されません。 <varname>$uncompression</varname> を <literal>-1</literal> にすると、 何段階でもすべてのファイルを伸長します。 </para> <note> <para> <varname>$URL</varname> で指定された圧縮ファイルについては、 <varname>$uncompression</varname> 変数の対象とはなりません。 </para> </note> <para> <varname>$directoryDepth</varname> パラメータは、 そのリーダーが読み込むディレクトリ数の制限値を指定します。 </para> </refsect1> <refsect1 id="package.fileformats.file-archive.readers.multireader"> <title>マルチリーダー</title> <para> マルチリーダーを使用すると、複数のソースをひとつにまとめることができます。 マルチリーダーを作成するには <command>File_Archive::readMulti()</command> 関数を使用します。 </para> <example> <title>マルチリーダー</title> <programlisting role="php"><![CDATA[ <?php // このリーダーには、ディレクトリの内容と archive.tar が含まれます $source = File_Archive::readMulti( array( File_Archive::read('directory'), File_Archive::read('archive.tar/') ) ); ?>]]></programlisting> </example> </refsect1> <refsect1 id="package.fileformats.file-archive.readers.readingcontent"> <title>データリーダーの中身の読み込み</title> <para> すべてのリーダーは、次のようなインターフェイスを提供しています。 </para> <itemizedlist> <listitem> <para><command>function next()</command></para> <para> ソース内の次のファイルに移動します。アーカイブの末尾に達したときに <literal>false</literal> を返します。 </para> </listitem> <listitem> <para><command>function getFilename()</command></para> <para> アーカイブ内で現在選択されているエントリのファイル名を返します。 </para> </listitem> <listitem> <para><command>function getStat()</command></para> <para> <function>stat</function> 関数と同様の値を返します。 完全な配列を返すとは限りません。<literal>array()</literal> を返す可能性もあります。 </para> </listitem> <listitem> <para><command>function getDataFilename()</command></para> <para> 最適化用に使用します。ソースが物理ファイルの場合にファイル名を、 それ以外の場合に <literal>null</literal> を返します。 </para> </listitem> <listitem> <para><command>function getData($length = -1)</command></para> <para> データをソースから読み込みます。 この関数は文字列を返します。その大きさは、以下のうちもっとも小さいものです。 <itemizedlist> <listitem> <para> <varname>$length</varname> <literal>&gt;= 0</literal> の場合の <varname>$length</varname> </para> </listitem> <listitem> <para> ファイルの終端 </para> </listitem> </itemizedlist> ファイルの終端に達した場合は、この関数は <literal>null</literal> を返します。 </para> </listitem> <listitem> <para><command>function skip($length)</command></para> <para> <command>getData($length)</command> と同じですが、データを返しません。 データリーダーの種類によっては、この関数のほうが <function>getData</function> よりもずっと効率的です。 </para> </listitem> <listitem> <para><command>function close()</command></para> <para> データリーダを使い終えた (ファイルハンドルのクローズなど...) 後でコールしなければなりません。 この関数は、最初に <function>next</function> をコールする前の状態に戻します。 これをコールすると、データリーダーを再度処理できるようになります。 </para> </listitem> </itemizedlist> <example> <title>データリーダーの中身の一覧の表示</title> <programlisting role="php"><![CDATA[ <?php $source->close(); // ソースの先頭に戻ります while($source->next()) { echo $source->getFilename() . "<br/>\n"; } ?>]]></programlisting> </example> </refsect1> <refsect1 id="package.fileformats.file-archive.readers.functionsusing"> <title>リーダーを使用する関数</title> <para> 引数としてリーダーを受け取る <classname>File_Archive</classname> のすべての関数は、文字列および配列の両方の形式を受け付けます。 文字列は、<command>File_Archive::read</command> 関数を用いて自動的にリーダーとして解釈されます。 配列はマルチリーダーと解釈されます。 </para> <para> リーダーは参照渡しとなるので、生の文字列や配列ではなく変数を渡す必要があります。 </para> <para> したがって、先ほどの例は次のように書き換えることもできます。 </para> <example> <title>マルチリーダー</title> <programlisting role="php"><![CDATA[ <?php // このリーダーには、ディレクトリの内容と archive.tar が含まれます File_Archive::extract( array( 'directory', 'archive.tar/' ), File_Archive::toArchive('test.zip') ); ?>]]></programlisting> </example> </refsect1> </refentry> http://cvs.php.net/viewvc.cgi/peardoc/ja/package/fileformats/file-archive/predicates.xml?view=markup&rev=1.1 Index: peardoc/ja/package/fileformats/file-archive/predicates.xml +++ peardoc/ja/package/fileformats/file-archive/predicates.xml <?xml version="1.0" encoding="utf-8" ?> <!-- $Revision: 1.1 $ --> <!-- EN-Revision: 1.1 Maintainer: takagi Status: ready --> <refentry id="package.fileformats.file-archive.predicates"> <refnamediv> <refname>述語</refname> <refpurpose>フィルタ</refpurpose> </refnamediv> <refsect1 id="package.fileformats.file-archive.predicates.intro"> <title>導入</title> <para> <classname>File_Archive</classname> では、 ソースからファイルを選択する際にフィルタの概念を使用します。 フィルタとはリーダーの一種であり、 <function>File_Archive::filter</function> 関数で作成することができます。 この関数には、述語を指定する必要があります。 述語を作成するには <command>File_Archive::pred*</command> 関数を使用します。 </para> <para> 標準の論理述語は次のとおりです。 </para> <itemizedlist> <listitem> <para> <command>predTrue()</command>: つねに true と評価されます </para> </listitem> <listitem> <para> <command>predFalse()</command>: つねに false と評価されます </para> </listitem> <listitem> <para> <command>predAnd($p1, $p2, ...)</command>: <literal>$p1 &amp;&amp; $p2 &amp;&amp; ...</literal> と評価されます </para> </listitem> <listitem> <para> <command>predOr($p1, $p2, ...)</command>: <literal>$p1 || $p2 || ...</literal> と評価されます </para> </listitem> <listitem> <para> <command>predNot($p)</command>: <literal>!$p</literal> と評価されます </para> </listitem> </itemizedlist> <para> ファイルのフィルタリング用に、その他の述語も用意されています。 </para> <itemizedlist> <listitem> <para> <command>predMinSize($size)</command>: サイズが <literal>&gt;= $size</literal> (バイト単位) であるファイルのみを残します </para> </listitem> <listitem> <para> <command>predMinTime($time)</command>: 最終更新時刻が $time (unix タイムスタンプ) 以降であるファイルのみを残します </para> </listitem> <listitem> <para> <command>predMaxDepth($depth)</command>: 公開名のディレクトリ階層が <varname>$depth</varname> より少ないファイルのみを残します </para> </listitem> <listitem> <para> <command>predExtension($list)</command>: 指定した拡張子のファイルのみを残します。 <varname>$list</varname> は拡張子の配列、あるいはカンマ区切り文字列となります </para> </listitem> <listitem> <para> <command>predEreg($ereg)</command>: 公開名が指定した正規表現にマッチするファイルのみを残します </para> </listitem> <listitem> <para> <command>predEregi($ereg)</command>: <function>predEreg</function> と同じですが、大文字小文字を区別しません </para> </listitem> <listitem> <para> <command>predMIME($mimes)</command>: 指定した MIME タイプのファイルを選択します。 配列あるいは文字列で指定することができ、ワイルドカードを使用することも可能です。 </para> </listitem> </itemizedlist> <example> <title>フィルタの例</title> <programlisting role="php"><![CDATA[ <?php // パスあるいはファイル名の中に 'a' を含むすべてのファイルを // tar アーカイブから取り出します File_Archive::extract( File_Archive::filter( File_Archive::predEreg('a'), File_Archive::read( 'archive.tar/', 'folder' ) ), File_Archive::toFiles() ); // ディレクトリを zip 圧縮します。サイズが 1MB より小さくて // 直近の 1 時間以内に更新されているファイルのみを圧縮します File_Archive::extract( File_Archive::filter( File_Archive::predAnd( File_Archive::predNot( File_Archive::predMinSize(1024 * 1024) ), File_Archive::predMinTime(time()-3600) ), File_Archive::read('directory') ), File_Archive::toArchive( 'directory.zip', File_Archive::toFiles() ) ); ?>]]></programlisting> </example> </refsect1> </refentry> http://cvs.php.net/viewvc.cgi/peardoc/ja/package/fileformats/file-archive/examples.xml?view=markup&rev=1.1 Index: peardoc/ja/package/fileformats/file-archive/examples.xml +++ peardoc/ja/package/fileformats/file-archive/examples.xml <?xml version="1.0" encoding="utf-8" ?> <!-- $Revision: 1.1 $ --> <!-- EN-Revision: 1.1 Maintainer: takagi Status: ready --> <refentry id="package.fileformats.file-archive.examples"> <refnamediv> <refname>例</refname> <refpurpose>シンプルな使用例</refpurpose> </refnamediv> <refsect1 id="package.fileformats.file-archive.examples.extractarchive"> <title>tar アーカイブのサブディレクトリへの展開</title> <para> この例では、<filename>archive.tar</filename> という tar アーカイブの内容を <filename>output/</filename> フォルダに展開します。 </para> <programlisting role="php"><![CDATA[ <?php require_once "File/Archive.php"; File_Archive::extract('archive.tar/', 'output'); ?> ]]></programlisting> </refsect1> <refsect1 id="package.fileformats.file-archive.examples.archivetostdout"> <title>Send a zip archive containing the content of a tar file to the standard output</title> <programlisting role="php"><![CDATA[ <?php require_once "File/Archive.php"; File_Archive::extract( // archive.tar の中身がルートフォルダにあらわれます (デフォルトの引数) 'archive.tar/', // そして書き出し先は ... File_Archive::toArchive( // zip アーカイブで、その名前は 'archive.zip', // archive.zip File_Archive::toOutput() // それが標準出力に送られます ) ); ?>]]></programlisting> </refsect1> <refsect1 id="package.fileformats.file-archive.examples.extractfile"> <title>アーカイブからのファイルの取り出し</title> <para> <function>extract</function> でファイルをアーカイブから取り出します。 取り出すファイルを指定する際には、 アーカイブ名を最初のフォルダとして指定します。 </para> <programlisting role="php"><![CDATA[ <?php require_once "File/Archive.php"; File_Archive::extract( 'archive.tar/inner.tgz/file.txt', File_Archive::toOutput() ); ?> ]]></programlisting> </refsect1> </refentry> <!-- 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 sgml-parent-document:nil sgml-default-dtd-file:"../../../../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 --> http://cvs.php.net/viewvc.cgi/peardoc/ja/package/fileformats/file-archive/examples-gallery.xml?view=markup&rev=1.1 Index: peardoc/ja/package/fileformats/file-archive/examples-gallery.xml +++ peardoc/ja/package/fileformats/file-archive/examples-gallery.xml <?xml version="1.0" encoding="utf-8" ?> <!-- $Revision: 1.1 $ --> <!-- EN-Revision: 1.1 Maintainer: takagi Status: ready --> <refentry id="package.fileformats.file-archive.examples-gallery"> <refnamediv> <refname>ギャラリーのファイルからの動的なアーカイブ生成</refname> <refpurpose>File_Archive で画像や動画を処理する方法</refpurpose> </refnamediv> <refsect1 id="package.fileformats.file-archive.examples-gallery.intro"> <title></title> <para> <classname>File_Archive</classname> の使用例のひとつとして考えられるのは、 ギャラリーの画像や動画のファイルから動的にアーカイブを生成することです。 </para> <para> 効率的に生成することを考えるなら、どのファイルフォーマットを選択するかが大事です。 選択肢をあげてみましょう。 </para> <qandaset> <qandaentry> <question><para>Tar</para></question> <answer> <para> <emphasis>利点</emphasis>: 効率よく作成できてメモリの使用量が一定、キャッシュは不要 </para> </answer> <answer> <para> <emphasis>欠点</emphasis>: 圧縮ができない (とはいえ、もともと画像や動画はそれ以上に圧縮するのは困難です)、 また Zip ほど広く知れ渡っていない </para> </answer> </qandaentry> <qandaentry> <question><para>Tgz, Tbz</para></question> <answer> <para> <emphasis>利点</emphasis>: 圧縮率が高く、メモリの使用量が一定 </para> </answer> <answer> <para> <emphasis>欠点</emphasis>: キャッシュができない。また、生成時に CPU にかなりの負荷がかかる </para> </answer> </qandaentry> <qandaentry> <question><para>Zip</para></question> <answer> <para> <emphasis>利点</emphasis>: 中間結果をキャッシュすることができる。 圧縮レベルを指定することができる。 幅広く用いられている。 </para> </answer> <answer> <para> <emphasis>欠点</emphasis>: 圧縮率が Tgz/Tbz より低い </para> </answer> </qandaentry> </qandaset> <para> ここでは Tar と Zip を取り上げます。Tgz や Tbz は、 アーカイブを "その場で" 作成するには CPU を食いすぎます。 </para> </refsect1> <refsect1 id="package.fileformats.file-archive.examples-gallery.targen"> <title>Tar の作成</title> <programlisting role="php"><![CDATA[ <?php require_once "File/Archive.php"; // $files は、アーカイブに追加するファイルへのパスの配列です File_Archive::extract( $files, File_Archive::toArchive( 'myGallery.tar', File_Archive::toOutput() ) ); ?> ]]></programlisting> </refsect1> <refsect1 id="package.fileformats.file-archive.examples-gallery.zipgen"> <title>Zip の作成</title> <para> Zip を使用する最大の利点は、リソースをあまり消費しないこと (結果をキャッシュできるので) と幅広く用いられている形式であることです。 とりうる方法は二通りあります。まずは未圧縮の Zip アーカイブを作成すること (画像ファイルや動画ファイルは、もともとそれ以上の圧縮を期待できないため)、 もうひとつはキャッシュシステムを利用して圧縮済みの Zip アーカイブを作成することです。 </para> <example> <title>その場での未圧縮 ZIP アーカイブの作成</title> <programlisting role="php"><![CDATA[ <?php require_once "File/Archive.php"; File_Archive::setOption('zipCompressionLevel', 0); // $files は、アーカイブに追加するファイルへのパスの配列です File_Archive::extract( $files, File_Archive::toArchive( 'myGallery.zip', File_Archive::toOutput() ) ); ?>]]></programlisting> </example> <example> <title>その場での圧縮 ZIP アーカイブの作成 (キャッシュを使用)</title> <programlisting role="php"><![CDATA[ <?php require_once "File/Archive.php"; require_once "Cache/Lite.php"; // $options 配列の意味については Cache_Lite のドキュメントを参照ください // fileNameProtection はデフォルトの true のままでなければなりません // automaticSerialization は不要なので false のままでなければなりません $options = array('cacheDir' => 'tmp'); File_Archive::setOption('cache', new Cache_Lite($options)); File_Archive::setOption('zipCompressionLevel', 9); // $files は、アーカイブに追加するファイルへのパスの配列です File_Archive::extract( $files, File_Archive::toArchive( 'myGallery.zip', File_Archive::toOutput() ) ); ?>]]></programlisting> </example> </refsect1> <refsect1 id="package.fileformats.file-archive.examples-gallery.puttingtogether"> <title>まとめ</title> <para> zip の作成と tar の作成はほとんど同じコードとなるので、 ユーザの選択内容に応じて処理を切り替えるコードをすっきりと書くことができます。 次のコードは、実際に私のサイトで使用しているものです。 </para> <example> <title>カスタムアーカイブ</title> <programlisting role="php"><![CDATA[ <?php $allowedFormats = array('tar', 'zip'); if (!in_array($_GET['type'], $allowedFormats)) { die('Type ' . htmlspecialchars($_GET['type']) . ' is either unknown or not allowed'); } require_once "File/Archive.php"; File_Archive::setOption('zipCompressionLevel', 0); /** * I skipped the generation of the $files array since it really * depends on you gallery and what files the user requires */ File_Archive::extract( $files, File_Archive::toArchive( 'myGallery.' . $_GET['type'], File_Archive::toOutput() ) ); ?>]]></programlisting> </example> </refsect1> </refentry> <!-- 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 sgml-parent-document:nil sgml-default-dtd-file:"../../../../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 --> http://cvs.php.net/viewvc.cgi/peardoc/ja/package/fileformats/file-archive/cache.xml?view=markup&rev=1.1 Index: peardoc/ja/package/fileformats/file-archive/cache.xml +++ peardoc/ja/package/fileformats/file-archive/cache.xml <?xml version="1.0" encoding="utf-8" ?> <!-- $Revision: 1.1 $ --> <!-- EN-Revision: 1.1 Maintainer: takagi Status: ready --> <refentry id="package.fileformats.file-archive.cache"> <refnamediv> <refname>キャッシュ</refname> <refpurpose>圧縮したファイルのキャッシュ</refpurpose> </refnamediv> <refsect1 id="package.fileformats.file-archive.cache.intro"> <title>導入</title> <para> <classname>File_Archive</classname> 1.4 では、 キャッシュを使用して zip 圧縮の結果を保存できるようになりました。 これを行うために、PEAR パッケージ <classname>Cache_Lite</classname> を使用しています。 </para> <para> zip ファイルを作成するには、まずされた圧縮ファイルを用意することになります。 たとえば、ファイル A、B および C を含むアーカイブと ファイル A および C を含むアーカイブのふたつを作成したい場合は、 A と C については 2 回圧縮する必要があります。 キャッシュを使用すると、最初の圧縮の際に圧縮したファイル A、B および C をキャッシュしておくことができ、2 回目の圧縮ではそれを再利用できるようになります。 </para> </refsect1> <refsect1 id="package.fileformats.file-archive.cache.examples"> <title>使用例</title> <para> キャッシュを使うのは (使うべきなのは)、同じファイルを含む zip アーカイブを動的に何度も作成しなければならない場合などです。 たとえば、あなたが公開している画像や動画などからユーザが選択した ファイルを zip 形式でダウンロードさせるといった場合がこれにあたります。 </para> <para> これをキャッシュを使わずに行うと、多くのユーザがアクセスした場合に 反応が非常に遅くなることでしょう。キャッシュを使えば、 同じファイルを何度も圧縮することはなくなります。 </para> <para> 私のマシン (工場出荷時のままの状態の thinkpad T42P) では、 キャッシュのない状態で 200MB の zip アーカイブを作成するのにかかった時間は 30 秒でした。キャッシュを使用した場合、まだキャッシュが作成されていないときは 32 秒かかりましたが、圧縮されるすべてのファイルがキャッシュに載った状態では 2 秒で処理が完了しました。 </para> </refsect1> <refsect1 id="package.fileformats.file-archive.cache.howtouse"> <title>キャッシュの使用法</title> <para> キャッシュの正体は Cache_Lite オブジェクトです。 つまり、まずこのパッケージをインストールしなければなりません。 インストールさえしてしまえば、あとは <function>File_Archive::setOption</function> 関数で <varname>cache</varname> パラメータを使用するだけです。 </para> <example> <title>キャッシュの準備</title> <programlisting role="php"><![CDATA[ <?php require_once "File/Archive.php"; require_once "Cache/Lite.php"; // キャッシュオブジェクトを作成します $cache = new Cache_Lite( array( // コンストラクタのパラメータは Cache_Lite のドキュメントを参照ください ) ); // File_Archive に対して、いま作成したキャッシュオブジェクトを使うように指示します File_Archive::setOption('cache', $cache); // あとはいつもどおりにアーカイブを作成します // archive.zip という名前のファイルを作業フォルダに作成します File_Archive::extract( 'folderToCompress', 'archive.zip' ); // アーカイブをユーザに送信します File_Archive::extract( 'folderToCompress', File_Archive::toArchive( 'archive.zip', File_Archive::toOutput() ) ); ?>]]></programlisting> </example> </refsect1> </refentry> http://cvs.php.net/viewvc.cgi/peardoc/ja/package/fileformats/file-archive/archmod.xml?view=markup&rev=1.1 Index: peardoc/ja/package/fileformats/file-archive/archmod.xml +++ peardoc/ja/package/fileformats/file-archive/archmod.xml <?xml version="1.0" encoding="utf-8" ?> <!-- $Revision: 1.1 $ --> <!-- EN-Revision: 1.1 Maintainer: takagi Status: ready --> <refentry id="package.fileformats.file-archive.archmod"> <refnamediv> <refname>アーカイブの変更</refname> <refpurpose>ファイルの削除や追加</refpurpose> </refnamediv> <refsect1 id="package.fileformats.file-archive.archmod.intro"> <title>導入</title> <para> <classname>File_Archive</classname> バージョン 1.3 では、既存のアーカイブを編集するための関数が新たに追加されました。 これらの関数を使用すると、既存のアーカイブからファイルを削除したり アーカイブにファイルを追加したりできるようになります。 </para> <para> <classname>File_Archive</classname> においては ファイルシステムは単なるリーダー/ライターであり、 変更内容を "実際の" アーカイブ (実際のファイル) に書き込んだりネストしたアーカイブ (別のアーカイブの内部にあるアーカイブ) に書き込んだりすることができます。 </para> </refsect1> <refsect1 id="package.fileformats.file-archive.archmod.remove"> <title>既存のアーカイブからのファイルの削除</title> <para> ファイルをアーカイブから削除するには、 <classname>File_Archive</classname> クラスの以下の関数のいずれかを使用します。 </para> <itemizedlist> <listitem> <funcsynopsis> <funcprototype> <funcdef> <function>remove</function> </funcdef> <paramdef>&amp;$pred</paramdef> <paramdef>$URL</paramdef> </funcprototype> </funcsynopsis> <para> 指定した条件を満たすすべてのファイルを <varname>$URL</varname> から削除します。 URL は <function>File_Archive::read</function> 関数と同じ形式のものです。 ネストしたアーカイブも使用することができます。 </para> </listitem> <listitem> <funcsynopsis> <funcprototype> <funcdef> <function>removeFromSource</function> </funcdef> <paramdef>&amp;$pred</paramdef> <paramdef>&amp;$source</paramdef> <paramdef>$URL = null</paramdef> </funcprototype> </funcsynopsis> <para> remove と同じですが、デフォルトのファイルシステムリーダーではなく <varname>$source</varname> を使用します。URL を省略した場合は <varname>$source</varname> がアーカイブでなければなりません。 ファイルはここから削除されます。 </para> </listitem> <listitem> <funcsynopsis> <funcprototype> <funcdef> <function>removeDuplicates</function> </funcdef> <paramdef>$URL</paramdef> </funcprototype> </funcsynopsis> <para> この関数は、<varname>$URL</varname> で指定したアーカイブから 重複しているファイルを削除します。直近のファイルのみを残します。 </para> <para> ファイルの更新時刻が記録されていない場合は、 一番古いものとみなします。 </para> <para> ふたつのファイルの更新時刻が同じ場合は、 アーカイブ内での位置がもっとも上にあるもの (通常は一番最後に追加したもの) を残します。 </para> </listitem> <listitem> <funcsynopsis> <funcprototype> <funcdef> <function>removeDuplicatesFromSource</function> </funcdef> <paramdef>&amp;$source</paramdef> <paramdef>$URL = null</paramdef> </funcprototype> </funcsynopsis> <para> <function>removeDuplicate</function> と同じですが、 デフォルトのファイルシステムリーダーではなく <varname>$source</varname> を使用します。URL を省略した場合は <varname>$source</varname> がアーカイブでなければなりません。 </para> </listitem> </itemizedlist> <para> これらの関数は、アーカイブの圧縮解除を再帰的には行わないことに注意しましょう。 </para> <example> <title>zip アーカイブからの jpg、gif そして bmp ファイルの削除</title> <programlisting role="php"><![CDATA[ <?php require_once "File/Archive.php"; File_Archive::remove( File_Archive::predExtension( array('jpg', 'jpeg', 'bmp', 'gif') ), 'archive.zip' ); ?>]]></programlisting> </example> <example> <title>ネストしたアーカイブからの画像ファイルの削除</title> <programlisting role="php"><![CDATA[ <?php require_once 'File/Archive.php'; File_Archive::remove( File_Archive::predMIME( array('image/*') ), 'archive.zip/data.tgz' ); ?>]]></programlisting> </example> </refsect1> <refsect1 id="package.fileformats.file-archive.archmod.add"> <title>アーカイブへのファイルの追加</title> <para> ファイルをアーカイブに追加するには、 <classname>File_Archive</classname> クラスの以下の関数のいずれかを使用します。 </para> <itemizedlist> <listitem> <funcsynopsis> <funcprototype> <funcdef> <function>appender</function> </funcdef> <paramdef>$URL</paramdef> <paramdef><parameter><optional>$unique = null</optional></parameter></paramdef> <paramdef><parameter><optional>$type = null</optional></parameter></paramdef> <paramdef><parameter><optional>$stat = array()</optional></parameter></paramdef> </funcprototype> </funcsynopsis> <para> URL で指定したアーカイブに追加します。 </para> <para> unique が <literal>true</literal> の場合は、アーカイブ内に 同じ名前のファイルがあればそれが削除されます。 <literal>null</literal> の場合はデフォルト設定 (変更するには <command>File_Archive::setOption('appendRemoveDuplicates', true/false))</command> を使用します (デフォルトは <literal>false</literal> です)。 </para> <para> アーカイブが存在しない場合は、指定したパラメータ (型が指定されていない場合は URL の拡張子で判断します) と stat 配列を使用して作成します。 </para> </listitem> <listitem> <funcsynopsis> <funcprototype> <funcdef> <function>appenderFromSource</function> </funcdef> <paramdef><parameter>&amp;$source</parameter></paramdef> <paramdef><parameter><optional>$URL = null</optional></parameter></paramdef> <paramdef><parameter><optional>$unique = null</optional></parameter></paramdef> <paramdef><parameter><optional>$type = null</optional></parameter></paramdef> <paramdef><parameter><optional>$stat = array()</optional></parameter></paramdef> </funcprototype> </funcsynopsis> <para> appender と同じですが、デフォルトのファイルシステムリーダーではなく <varname>$source</varname> を使用します。 </para> </listitem> </itemizedlist> <para> これらの関数はいずれも、ライターを返します。 これは、先ほどのように extract 関数で使用することができます。 </para> <example> <title>アーカイブへのフォルダの追加</title> <programlisting role="php"><![CDATA[ <?php require_once "File/Archive.php"; File_Archive::extract( File_Archive::read('folder'), File_Archive::appender('archive.zip') ); ?>]]></programlisting> </example> <para> ライターではなく文字列を関数で使用した場合は、 <function>File_Archive::appender</function> で文字列が変換されることに注意しましょう。 したがって、先ほどの例はこのように書き直すこともできます。 </para> <example> <title>アーカイブへのフォルダの追加</title> <programlisting role="php"><![CDATA[ <?php require_once "File/Archive.php"; File_Archive::extract( $src = 'folder', $dest= 'archive.zip' ); ?>]]></programlisting> </example> </refsect1> </refentry>